Components ========== BadGUI provides a comprehensive set of components that map to Quasar Framework components, giving you access to a rich, Material Design-based UI library. All components support NiceGUI-style method chaining and proper context manager patterns. Base Component -------------- All BadGUI components inherit from the ``Component`` class, which provides common styling methods. .. autoclass:: badgui.core.Component :members: :undoc-members: Text Components --------------- Label ~~~~~ The ``label`` component creates text elements and headings. .. code-block:: python import badgui as bg # Basic label bg.label("Hello World") # With styling bg.label("Title").classes("text-h3 text-primary") bg.label("Subtitle").classes("text-h6 text-grey-7") # With inline styles bg.label("Custom").style("color: red; font-weight: bold") **Generated Output:** ```` Input Components ---------------- Input ~~~~~ The ``input`` component creates text input fields. .. code-block:: python # Basic input bg.input(placeholder="Enter text") # Styled input bg.input(placeholder="Name").props("filled dense") bg.input(placeholder="Email").props('outlined label="Email Address"') # With validation styling bg.input().classes("q-mb-md").props("filled error-message=Required") **Generated Output:** ```` Interactive Components ---------------------- Button ~~~~~~ The ``button`` component creates clickable buttons. .. code-block:: python # Basic button bg.button("Click Me") # Styled buttons bg.button("Primary").props("color=primary") bg.button("Secondary").props("color=secondary outline") bg.button("Icon").props("icon=star push") # With custom styling bg.button("Custom").classes("my-custom-button").style("border-radius: 20px") **Generated Output:** ```` Card Components --------------- Card ~~~~ The ``card`` component creates Material Design cards for grouping content. .. code-block:: python # Basic card with bg.card() as my_card: my_card.classes("q-ma-md") with bg.card_section(): bg.label("Card Title").classes("text-h5") bg.label("Card content goes here") **Generated Output:** ```` Card Section ~~~~~~~~~~~~ The ``card_section`` component creates sections within cards. .. code-block:: python with bg.card(): with bg.card_section(): bg.label("Main content") with bg.card_section(): bg.label("Additional content") **Generated Output:** ```` Card Actions ~~~~~~~~~~~~ The ``card_actions`` component creates action areas in cards. .. code-block:: python with bg.card(): with bg.card_section(): bg.label("Card content") with bg.card_actions(): bg.button("Action 1") bg.button("Action 2") **Generated Output:** ```` Tab Components -------------- Tabs ~~~~ The ``tabs`` component creates tab navigation. .. code-block:: python with bg.tabs() as main_tabs: main_tabs.classes("text-primary") with bg.tab("tab1", "Tab 1"): pass with bg.tab("tab2", "Tab 2"): pass **Generated Output:** ```` Tab ~~~ The ``tab`` component creates individual tab items. .. code-block:: python with bg.tabs(): with bg.tab("home", "Home"): pass # Tab content defined in tab_panel **Generated Output:** ```` Tab Panels ~~~~~~~~~~ The ``tab_panels`` component creates content containers for tabs. .. code-block:: python with bg.tab_panels() as panels: panels.classes("q-pa-md") with bg.tab_panel("tab1"): bg.label("Content for Tab 1") with bg.tab_panel("tab2"): bg.label("Content for Tab 2") **Generated Output:** ```` Layout Components ----------------- Header ~~~~~~ The ``header`` component creates page headers with navigation. .. code-block:: python with bg.header() as page_header: page_header.classes("bg-primary text-white q-pa-md") with bg.row() as nav_row: nav_row.classes("items-center justify-between") bg.label("Site Title").classes("text-h4") # Navigation items... **Generated Output:** ```` Footer ~~~~~~ The ``footer`` component creates page footers. .. code-block:: python with bg.footer() as page_footer: page_footer.classes("bg-dark text-white q-pa-md") bg.label("© 2024 My Website. Built with BadGUI.") **Generated Output:** ```` Media Components ---------------- Image ~~~~~ The ``image`` component displays images with Quasar's optimized image loading. .. code-block:: python # Basic image bg.image("https://example.com/image.jpg") # With styling bg.image("https://picsum.photos/300/200").classes("rounded-lg shadow-md") # Responsive image bg.image("/local/image.png").classes("full-width") **Generated Output:** ```` Icon ~~~~ The ``icon`` component displays Material Design icons. .. code-block:: python # Basic icon bg.icon("home") # With color and size bg.icon("star", color="yellow", size="2rem") # With styling bg.icon("favorite", color="red").classes("q-mr-sm") **Generated Output:** ```` Navigation Components Link ~~~~ The ``link`` component creates router navigation links. .. code-block:: python # Basic link bg.link("Home", "/") # Styled as button bg.link("About", "/about").classes("q-btn q-btn-primary") # With props bg.link("Contact", "/contact").props("exact") **Generated Output:** ```` Layout Components ----------------- Row ~~~ The ``row`` component creates horizontal layout containers. .. code-block:: python # Basic row with bg.row(): bg.label("Item 1") bg.label("Item 2") # Styled row with bg.row().classes("q-gutter-md justify-center") as row: row.style("background: #f5f5f5; padding: 16px") bg.button("Button 1") bg.button("Button 2") **Generated Output:** ``
`` Column ~~~~~~ The ``column`` component creates vertical layout containers. .. code-block:: python # Basic column with bg.column(): bg.label("Item 1") bg.label("Item 2") # Styled column with bg.column().classes("q-gutter-sm items-center") as col: col.style("min-height: 200px") bg.label("Centered Item 1") bg.label("Centered Item 2") **Generated Output:** ``
`` Component Properties -------------------- All components support these common properties: Classes ~~~~~~~ Set CSS classes using the ``.classes()`` method: .. code-block:: python component.classes("class1 class2 class3") component.classes(add="new-class", remove="old-class") component.classes(replace="completely-new-classes") Props ~~~~~ Set component properties using the ``.props()`` method: .. code-block:: python component.props("prop1 prop2=value") component.props('prop3="quoted value"') component.props(prop4=True, prop5="value") Styles ~~~~~~ Set inline CSS styles using the ``.style()`` method: .. code-block:: python component.style("color: blue; background: white") component.style(color="blue", backgroundColor="white") Method Chaining ~~~~~~~~~~~~~~~ All styling methods return the component, allowing for method chaining: .. code-block:: python bg.button("Styled Button")\ .classes("q-btn-primary q-ma-md")\ .props("push icon=star")\ .style("border-radius: 10px") Component Lifecycle ------------------- Components are created when you call their factory functions (``bg.label()``, ``bg.button()``, etc.) and are automatically added to the current page context. The component tree is built during Python execution and then converted to Vue.js templates during the build process. Custom Components ----------------- While BadGUI focuses on providing a curated set of components, you can extend the framework by creating custom components: .. code-block:: python from badgui.core import Component import badgui as bg def custom_card(title, content): \"\"\"Create a custom card component.\"\"\" component = Component('q-card') component.classes("q-ma-md") # Add title title_comp = Component('q-card-section', text=title) title_comp.classes("text-h6") component.add_child(title_comp) # Add content content_comp = Component('q-card-section', text=content) component.add_child(content_comp) return bg.app._get_current_page()._add_component(component) # Usage with bg.page("/", "CustomDemo"): custom_card("My Card", "This is custom card content") This approach allows you to create reusable custom components while maintaining compatibility with BadGUI's styling system.