{"id":21436990,"url":"https://github.com/axfab/kora-gum","last_synced_at":"2025-03-16T23:24:15.041Z","repository":{"id":74655622,"uuid":"127338821","full_name":"AxFab/kora-gum","owner":"AxFab","description":"Graphic User-interface Module. This is the default render library for KoraOS.","archived":false,"fork":false,"pushed_at":"2022-08-07T16:24:37.000Z","size":327,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-01-23T09:35:31.789Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AxFab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-29T19:35:10.000Z","updated_at":"2023-11-02T09:47:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"fce54495-7f1c-42f6-9cd3-df6621251cd3","html_url":"https://github.com/AxFab/kora-gum","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxFab%2Fkora-gum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxFab%2Fkora-gum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxFab%2Fkora-gum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxFab%2Fkora-gum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AxFab","download_url":"https://codeload.github.com/AxFab/kora-gum/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243945889,"owners_count":20372951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-23T00:17:14.394Z","updated_at":"2025-03-16T23:24:15.034Z","avatar_url":"https://github.com/AxFab.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gum - Graphical User-interface Module\n\nThe Gum library is the default gui library for Kora system. It's provide a\nrealy basic interface for regular framed applications.\n\nThe library doesn't provide widgets like most commun UI library. Unstead it\nprovide an abstract to an even more basic element refrered to as a __cell__.\n\nA cell is a rectangle store in a tree, for which may be associated a\nbackground, a border or a text. Some others attributes are attached to each\ncell in order to control their layout and behaviour.\n\nCells are the basic building block on which more complicated widgets are\ncreated.\n\n\n## Build a interface\n\nA cell-tree, can be created programmaticaly or imported from an XML file,\nallowing to specifiy a large variaty of parameters. In order to share some\nproperties, the skins (or style) of a cell is stored in a seperated\nstructure. Those can be pre-imported using a file with a CSS-like format.\n\nThe library provide some method to create compatible surface but this part is\ndelegate to an external library. By default, GUM use __cairo-graphics__ as\npainter. In turn _Cairo_ required also an external library to send surface to\n_a window manager_. It can be _xlib_ on linux, or _frame buffers_ on KoraOS.\n\nThe window manager used for the window will send back events to the\napplications which will be converted by GUM event manager and will triggers\napplication routines.\n\n\nHere's an exemple of a basic GUM application (C code only).\n\n```c\nvoid on_click(GUM_event_manager *evm, GUM_cell *cell, int event);\n\nint main() {\n    /* Load resources to create cell-tree */\n    GUM_skins *skins = gum_skins_loadcss(NULL, \"./resx/app.css\");\n    root = gum_cell_loadxml(\"./resx/app.xml\", skins);\n    if (root == NULL) {\n        printf(\"Unable to create render model.\\n\");\n        return -1;\n    }\n\n    /* Create a surface to use as window */\n    GUM_surface *win = gum_create_surface(width, height);\n    if (win == NULL) {\n        printf(\"Unable to initialize window.\\n\");\n        return -1;\n    }\n\n    /* The event manager use the surface to paint cells and transform\n       user-interaction to events */\n    GUM_event_manager *evm = gum_event_manager(root, win);\n\n    /* Now, application can bind cell's events to application routines... */\n    gum_event_bind(evm, gum_get_by_id(root, \"my-button\"), GUM_EV_CLICK, on_click);\n    gum_event_bind(evm, gum_get_by_id(root, \"close-button\"), GUM_EV_CLICK, gum_on_close);\n\n    gum_event_loop(evm);\n\n    /* Release ressources */\n    gum_destroy_manager(evm);\n    gum_destroy_surface(win);\n    gum_destroy_cells(root);\n    gum_release_skins(skins);\n    return 0;\n}\n\n```\n\n\n### Cells XML format\n\n On a XML file, each DOM element correspond to a new cell. Note that no other\n XML node will be read (text node, comment or CDATA are all ignored by the loader).\n The tag-name of the element will be used to try matching a pre-defined skin.\n If not, no skins will be attached.\n\n Here's the list of attribute supported, with their type:\n\n - `id`: _string_. This filed should be uniq, as it will be used to identify the cell on the tree.\n - `left`: _css size_. For absolute layout, offset between the left of cell and left of container.\n - `right`: _css size_. For absolute layout, offset between the right of cell and right of container.\n - `horizontal-center`: _css size_. For absolute layout, offset between the center of cell and center of container.\n - `min-width`: _css unsigned_. Minimum width required to display the cell.\n - `width`: _css unsigned_ or _\"wrap\"_ keyword.\n - `top`: _css size_. For absolute layout, offset between the top of cell and top of container.\n - `bottom`: _css size_. For absolute layout, offset between the bottom of cell and bottom of container.\n - `vertical-center`: _css size_. For absolute layout, offset between the middle of cell and middle of container.\n - `min-height`: _css size_. Minimum height required to display the cell.\n - `height`: _css unsigned_ or _\"wrap\"_ keyword.\n - `gap-x`: _css size_.\n - `gap-y`: _css size_.\n - `gap`: Alias for both `gap-x` and `gap-y`.\n - `padding-left`: _css size_.\n - `padding-right`: _css size_.\n - `padding-top`: _css size_.\n - `padding-bottom`: _css size_.\n - `padding`: Alias for all size paddings.\n - `text`: _string_.\n - `img`: _string_. Name of the image to draw on the cell.\n - `layout`: _enum_. The name of the layout used to set children position and size.\n - `editable`: _boolean_. Tell the cell text might be edited using keyboard if the cell have focus.\n - `solid`: _boolean_. Tell the cell to react with pointer events.\n - `overflow-x`: _boolean_.\n - `overflow-y`: _boolean_.\n - `substyle`: This flag can be used for item which are not `solid` but for which the skin should change in case parent item skin does. If parent also use `substyle` propagate to next parent.\n\n Types:\n\n - _string_: Any text.\n - _enum_: A keyword amongst several possibilitiy.\n - _boolean_: Either true or false, other value have no effect.\n - _css size_: An double value follow by the unit used (`px`, `pt`, `mm`, `in`, `dp`, `%`);\n - _css unsigned_: Like a CSS size, but can only be positive.\n\n\n## Layouts\n\nEven if you can set position and size for each cell individualy chance are\nyou'll quickly wanna cells to oragnize themself automatically. The only way to\ndo that is to give them some rules to place themself. The library provide\nseveral smart solutions that can place cells inside a container. Those\nsolution are called layouts. Here's the basic layout the library provide:\n\n - _Absolute_: Children cells are placed themself depending on the space\n   given by their container cell.\n - _Groups_: At the number of 8. Cells can be placed in a single line or\n   column, each one after an other. Ideal for list, toolbars, navbars...\n - _Grids_: Cell are placed in line or columns, but once the place is fulled,\n   next cells will be placed beside, creating a sort of table. Options\n   provide up to 6 different layouts.\n\n \u003e Those pretty straigth-forward layout defined how a cell-container place\n \u003e their direct children. This allow for a lot configuration but isn't flexible\n \u003e enough to provide a full HTML like layout -- probably the most complex out-there.\n\nEach of those layout might use some cells-attribute to place their childrens.\nNote that distances in GUM can be expressed in 6 different units:\n\n - in pixels `px`: Give the final pixels length.\n - in points `pt`: Depend of resolution we can place 72 points in one inch (2.54cm).\n - in points `mm`: Depend of resolution will match 1 mm on the screen.\n - in points `in`: Depend of resolution will match 1 inch on the screen.\n - in points `dp`: Depend of viewport settings, used to take grossly-around some space on screen depending on device (TV, mobile...) from 0.75 to 5 pixels.\n - in points `%`: Is relative to parent size.\n\n### Absolute\n\nThis layout give freedom to children cells to place themself whereever in the\ncontainer area. This means children attribute will be used to place themself.\nA group of five attribute are used for horizonal positioning, sames for\nvertical. We will take horizontal exemple.\n\nYou can fix the position of the left side relative to the left of the\ncontainer. You can also fix the position of the right side. Positive values\nfor this attribute will always place you inside the container (meaning left\nand right offsets are reversed). You can also specify the width of the item,\nwhich will be use only if one of the left or right attirbute is not used.\nMin-width attribute will however always be used. In case those attributes\naren't enough we look at the last attribute center which give an offset\nbetween the center of the cells and the center of the containers.\n\nSame attributes exists for vertical positioning (using top, bottom and height).\n\n\n### Groups and Grids\n\nDeclinaision of those layouts are made to control the size of the children.\n\nFor vertical groups, item can be place at the left, the right, centered or\nfillout all the width available. Same options exists for horizontal group\n(with top or bottom).\n\nGrid give three choice for chidren size, either each item take the minium size,\nor their all take the size of the largest item, or a compromise they take the\nsize of the largest item on the same row.\n\n\n## Manipulating the cell tree\n\n\n\n\n## Play with Skins\n\n - `background`: -\n - `shadow`: _Work-in-progress_\n - `color`: -\n - `border-color`: -\n - `border-color`: -\n - `border-top-left-radius`: -\n - `border-top-right-radius`: -\n - `border-bottom-left-radius`: -\n - `border-bottom-right-radius`: -\n - `border-radius`: Alias for all `border-*-*-radius`.\n - `width`: -\n - `height`: -\n - `text-align`: -\n - `vertical-align`: -\n\n \u003e At this moment, background only support one color. I don't plan in\n \u003e supporting image as they should use cell attributes. However I add support\n \u003e for gradient. For the moment they can only be used with temporary\n \u003e attributes `background-gradient` and `gradient-angle`.\n\n\nhttps://github.com/tronkko/dirent/blob/master/include/dirent.h\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxfab%2Fkora-gum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxfab%2Fkora-gum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxfab%2Fkora-gum/lists"}