fbui | Framebuffer-based graphical environment |
| download: https://git.y1.nz/archives/fbui.tar.gz | |
| README | Files | Log | Refs |
libfbui/API.txt
1
2 The FBUI library
3 Copyright (C) 2004 by Zachary Smith.
4 _________________________________________________________________
5
6 Using the library is actually not necessary since any program
7 can operate the FBUI ioctls itself. However the library
8 is helpful in that it saves time and effort and provides some
9 abstractions.
10
11 Display struct
12 --------------
13 With FBUI version 0.9 and above, each application can multiple
14 windows. However you still must open the display by calling
15 fbui_display_open(), which generates the Display struct.
16 Before exiting, you should call fbui_display_close().
17
18 Window struct
19 -------------
20 Each application can only many windows. There is a limit on the
21 number of windows per virtual console however that in theory
22 can be changed before compiling the kernel.
23
24 Queueing
25 --------
26 The FBUI library implements queueing of drawing commands since
27 doing this makes more efficient use of the ioctl interface.
28 Therefore you periodically need to call fbui_flush to make
29 drawing happen. However some commands cause a flush to occur
30 anyway because they involve data that might change before the
31 queue is flushed. For instance fbui_draw_string does this.
32
33 Fonts
34 -----
35 FBUI does not cache font metrics or bitmaps in kernel space.
36 Therefore each application must load the fonts it needs into
37 its own memory. FBUI library does not yet cache font info
38 nor does it allow any single process to act as a font server.
39
40 Using FBUI Library
41 ------------------
42 It is best to look at a sample application to get an idea of how
43 to use FBUI library. However here is a quick overview.
44
45 In main you want to:
46
47 1. load any fonts, perhaps exit if unavailable
48 2. call fbui_display_open to get the Display
49 3. call fbui_window_open for any windows with desired arguments
50 4. request any Alt-key accelerators if you need them; be sparing.
51 5. event loop: break out of it when done
52 6. optionally call fbui_window_close for each window
53 7. call fbui_display_close (which also calls fbui_window_close)
54 8. free up any Font objcts
55
56 In the event loop you must:
57
58 1. either wait for events, or poll for events e.g. 2-10 times
59 per second
60 2. process events, e.g. mouse motion, keypresses, expose;
61 the Event struct should have all the event data you need.
62
63 Expose
64 ------
65 In windowing systems that have overlapping windows,
66 expose events are for parts of windows. In FBUI, Expose
67 covers the entire window.
68
69 fbui_display_open
70 -----------------
71 This routine produces the Display struct and opens
72 the framebuffer.
73
74 fbui_window_open
75 ----------------
76 This routine opens a single window for the process.
77 You can specify a window location and size, but these can be
78 overridden using command line arguments.
79
80 You can call fbui_open many times, but keep in mind
81 there is an upper limit per VC on the number of windows.
82
83 You can specify a program type, which is a hint to the
84 window manager as to where the window should be placed.
85 fbwm ignores this, but for fbpm it is vital.
86
87 Another parameter is the desired virtual console. A value
88 of -1 means the current one. Otherwise 0..5 are the consoles
89 available.
90
91 Drawing
92 -------
93 Drawing is easy. As previously stated, commands are
94 queued until a flush. You can draw lines, points,
95 rectangles, horizontal lines, vertical lines. You can
96 fill areas, clear the window. Later I will add
97 arcs and maybe, just maybe, anti-aliased lines.
98 You can also draw text if you're read in a font.
99
100 Window Manager, Panel Manager
101 -----------------------------
102 Programs fbwm and fbpm are optional. But they are useful,
103 especially the Panel Manager fbpm which is the focus
104 of my window manager development.
105
106 The Panel Manager's purpose is to organize the user interface
107 into standard functional areas and thereby make work with the
108 computer easier and quicker.
109
110 Program Type Hint
111 -----------------
112 If no window manager is yet running, this datum will be
113 ignored. If there is a wm, the program type will result
114 in a window being hidden upon creation and its need_placement
115 flag set. The window manager will get word of the window's
116 creation and resize/position it.
117
118 Errors
119 ------
120 If your program needs to exit rapidly, use the FATAL
121 macro, which takes a string argument. This macro
122 closes all windows and the display.
123
124 If you need to print an FBUI error code, call
125 fbui_print_error.
126
127 Signals
128 -------
129 Several common error-related signals are caught by
130 libfbui and should result in all windows being closed.
131
132 Zombie Windows
133 --------------
134 If by chance an FBUI program dies without its window(s)
135 being closed, FBUI will eventually remove such windows
136 automagically.
137
138 -end-
139
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.