Skip to content

Latest commit

 

History

History
389 lines (249 loc) · 11.1 KB

README.md

File metadata and controls

389 lines (249 loc) · 11.1 KB
Raw

htagUI

This is a (basic) UI toolkit for htag apps. Contrario to htbulma, this one is a minimal toolkit, providing only useful and solid widgets, and will be maintained (you can use it ;-)).

Test

Package version

here is a minimal example in the pyscript/runner

roadmap

  • provide a darker theme css
  • test test & test, to be rock solid
  • be available in htag4brython too, with the same apis.
  • perhaps provide version using "shoelace web components", or "simple bulma styles" (like htbulma) ... but the basics version (current one) will always be available, with its minimal footprint (js/css dependancies in mind)

INSTALL

python3 -m pip install -U htagui

note: it will install htag and htagui, and provide the ui in the htag namespace (htag.ui)

A hello world could be :

from htag import Tag, Runner, ui

class MyApp(ui.App):
    def init(self):
        self <= ui.Button("test", _onclick=lambda ev: self.ui.alert( "hello world" ) )

if __name__ == "__main__":
    Runner(MyApp).run()

It provides some (ready-to-use) Htag Objects, and some utilities methods.

Object App

This is a surcharge of Tag.body( ... ) which auto provide an ui property on the instance, to interact with Dialog features

In place of:

class MyApp(Tag.body):
    def init(self):
        self.ui = ui.Dialog(self)   # <- it will do that, automatically
        self <= ui.Button("test", _onclick=lambda ev: self.ui.alert( "hello" ) )

you can do :

class MyApp(ui.App):
    def init(self):
        self <= ui.Button("test", _onclick=lambda ev: self.ui.alert( "hello" ) )

Object Button

A simple surcharge of Tag.button(...), to define a css class

import htagui as ui
self <= ui.Button("my button",_class="myclass", _onclick = myevent )

Object Input

A simple surcharge of Tag.input(...), to define a css class

import htagui as ui
self <= ui.Input(_value="my value", _name="myfield", _class="myclass", _required=True )

Availables managed types (setted with _type) params:

  • text : the default one (if omitted): an input text
  • checkbox : a checkbox
  • radio : a radio button (non sense : use ui.Radios or uiIRadios !)
  • range : a slider/range

For text: a special field "_label" will set the html "placeholder" attribut.

Object Textarea

A simple surcharge of Tag.textarea(...), to define a css class

import htagui as ui
self <= ui.Textarea("my value", _name="myfield", _class="myclass", _required=True )

A special field "_label" will set the html "placeholder" attribut.

Object Spinner

A spinner object.

import htagui as ui
self <= ui.Spinner()

Objets "I-fields"

Theses are interactive/reactive fields, which are automatically synced between client and server side, thru a 'value' property

  • IText .. an input of type text
  • ITextarea ... a textarea
  • IBool ... an input of type checkbox
  • IRange ... an input of type range
  • ISelect ... a multichoice select/option
  • IRadios ... a multichoice radio buttons

Object Select

An htag class to help to create "select/option" html tags, using a dict of {value:title, ...}.

import htagui as ui
self <= ui.Select( dict(a="A",b="B"), _value="a", _name="myfield" )

Object Radios

An htag class to help to create "radio button choices" html tags, using a dict of {value:title, ...}.

import htagui as ui
self <= ui.Radios( dict(a="A",b="B"), _value="a", _name="myfield" )

Object Menu

An htag class to help to create a (first-level) menu and menu items, using a dict of {title:callback,...}

import htagui as ui
ux = ui.Dialog(self)
entries={
    "menu1": lambda: ux.notify("menu1"),
    "menu2": lambda: ux.notify("menu2"),
    "menu3": lambda: ux.notify("menu3"),
}  
self <= ui.Menu( entries )

Object Form

A simple surcharge of Tag.form(...) where you can define a callback to call a method wich will receive a python "dict" of all named inputs defined in the form.

import htagui as ui
ux = ui.Dialog( self )
form = ui.Form( onsubmit=lambda dico: ux.notify(str(dico)) )
form <= ui.Input(_name="mystring",_placeholder="input something")
form <= ui.Button("ok")
self <= form

Object FileUpload

A simple surcharge of Tag.input( _type='file'...) which call a method to upload the selected file.

import htagui as ui

def uploaded(name:str, content:bytes):
    print(name,content)

self <= ui.FileUpload( uploaded , _multiple=True)

Object Tabs

An htag class to easily create tabs structure. And provides somes attributs/methods to interact with it.

import htagui as ui
tab1 = Tag.div("content1",name="tab1") # tab object needs a `name` property !
tab2 = Tag.div("content2",name="tab2")
t = ui.Tabs( tab1, tab2 )
self += t

method t.add_tab( obj )

A method to add dynamically a tab instance, which is automatically selected. (note that the tab object needs a name property !)

property t.selected

Dynamic property to retrieve or select the current selected tab.

event "onchange"

Event which is called when selected index changes.

Object Dialog

Expose "Dialog boxes" with methods on the instance. Note that, there can be only one dialog at a time (except toast notification)

import htagui as ui
dialog = ui.Dialog( self )

method dialog.alert(obj, size:float=None)

(like js window.alert(...)) Display a modal dialog box containing the object 'obj' (obj must be str'able)

size is a float to force the percent of width on the dialog box. If None, it will use the default from the ui used.

method dialog.confirm(obj, cbresponse=lambda bool)

(like js window.confirm(...)) Display a modal dialog box containing the object 'obj' (obj must be str'able), and let the user click on Yes|No buttons, which will call the cbresponse callback with True or False ...

method dialog.prompt(title, value=None, cbresponse=lambda val)

(like js window.prompt(...)) Display a modal dialog letting the user edit the value in an Input box, with a title (title must be str'able). When the user click the OK button the value is sent in the callback cbresponse. (clicking the cancel button does nothing, except close the dialog)

method dialog.notify(obj, time=2000)

Display a toast message (notification), in the right-bottom ... during 2000 ms. (currently toast messages are not stacked)

method dialog.pop(obj, xy:tuple)

Display an object, at coords (x,y).

ex "create a popmenu", using "Menu object"

import htagui as ui
dialog = ui.Dialog(self)
entries={
    "menu1": lambda: dialog.notify("menu1"),
    "menu2": lambda: dialog.notify("menu2"),
    "menu3": lambda: dialog.notify("menu3"),
}  
self <= ui.Button("pop menu", _onclick=lambda ev: dialog.pop( ui.Menu(entries) ,(ev.clientX,ev.clientY)) )

note: it ensures that the object is fully visible in the inner window.

method dialog.drawer(obj, mode="left")

Display a drawer, in the left-side. mode can be left,right,top,bottom.

method dialog.page(obj=None)

Display a full page 'obj', or remove page if obj is None. (note that ui.close() does not close the page)

method dialog.block(obj=None)

Display a modal dialog box containing the object 'obj'. But the dialog is not closable, so be sure to provide a way to close it.

method dialog.close()

Close programatically, the current ui dialog.

method dialog.clipboard_copy(txt:str)

Copy the txt in the clipboard

method dialog.clipboard_paste( lambda content )

Call the callback with the text content from the clipboard. (user may need to authorize the interaction from the navigator)

method dialog.download( name:str, content:bytes ):

Force the navigator to download a file named 'name', with the content bytes 'content' into the browser.

Object HSplit & VSplit

A Tag object to use "SplitJS"

import htagui as ui
split = ui.HSplit( Tag.div(1), Tag.div(2), sizes=[60,40], minSize=100, _style="border:2px solid red;height:100px" )
self <= split

methods: split.setSizes( [50,50] ) split.onchange = lambda object: print( object.sizes ) # event

Object Sortable

A component to let the user reorder items using drag'n'drop.

ll=[Tag.div(f"Item {i} (drag me)",value=i) for i in range(10)]
        
def onchange(o:ui.Sortable):
    print( str([i.value for i in o.values]) )

self <= ui.Sortable(ll,onchange=onchange)

Object VScroll

A component to help you to create an infinite scroller.

def feed():
    yield [Tag.div(i) for i in range(20) ]

self <= Tag.div(_style="height:200px; border:1px solid red;" ) <= ui.VScroll( feed )

This component should be embbeded in an element which have a constraint on its height. The given callback should yield Tag(s) (or None to finnish the endless scroll)

Object VScrollPager

A component (which inherit from VScroll) to present a finnished list of items in an "on-demand" way (create items on-demand), can contain a big amount of data.

ll=[lambda i=i: MyObject(i) for i in range(1,200_000_000)]
self <= Tag.div(_style="height:200px; border:1px solid red;" ) <= ui.VScrollPager(ll,preload=50,moreload=10,endzone=50)

This component should be embbeded in an element which have a constraint on its height. preload is the number of items which will be created (it should overflow on height). moreload is the number of items which will be loaded when scrolling is in the endzone pixels at the end.

Note that the list is a list of lambda (List[Callable[[], Tag]]) to create the rendering on-demand.

Object View

A view component which handle the browser navigation mechanism (go back)

IMPORTANT:

  • this component is here for tests only (it may disappear if real problems)
  • FOR POWER USERS : may be used as first class, and you need to understand how htag works, and how the browser history works ! (if the object is deleted -> nothing work)

TODO: make a better good example !

default_view=Tag.div("Default view")

v = ui.View( default_view, _style="border:1px solid red;width:100%;height:400px" )

self <= ui.Button("p1", _onclick = lambda ev: v.go( Tag.div("p1") ))
self <= ui.Button("p2", _onclick = lambda ev: v.go( Tag.div("p2") ))
self <= v

Object Grid

signature : Grid(format,vformat="auto",gap="1px",**a)

A simple grid container

example:

g = Grid("1fr 1fr 2fr")
g <= Tag.div( "2colums",_style="grid-column:1 / 3")    
g <= Tag.div( "1column")

utilities methods

hflex & vflex

Methods to create an HBox or VBox htag class (flexbox horizontal or vertical, with nowrap mode)

import htagui as ui
HBox = ui.hflex(50, 50)  # create a hbox of 2 elements of 50% each
self <= HBox( Tag.div(1), Tag.div(2) )