You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
400 lines
8.9 KiB
400 lines
8.9 KiB
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:** ``<q-item-label>`` |
|
|
|
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:** ``<q-input>`` |
|
|
|
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:** ``<q-btn>`` |
|
|
|
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:** ``<q-card>`` |
|
|
|
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:** ``<q-card-section>`` |
|
|
|
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:** ``<q-card-actions>`` |
|
|
|
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:** ``<q-tabs>`` |
|
|
|
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:** ``<q-tab>`` |
|
|
|
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:** ``<q-tab-panels>`` |
|
|
|
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:** ``<q-header>`` |
|
|
|
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:** ``<q-footer>`` |
|
|
|
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:** ``<q-img>`` |
|
|
|
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:** ``<q-icon>`` |
|
|
|
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:** ``<router-link>`` |
|
|
|
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:** ``<div class="row">`` |
|
|
|
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:** ``<div class="column">`` |
|
|
|
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. |