Repository navigation
Expand file tree
/
Copy pathpackages.txt
More file actions
155 lines (108 loc) · 15.9 KB
/
Copy pathpackages.txt
File metadata and controls
155 lines (108 loc) · 15.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
# The Codebot Library
The Codebot library is a collection of Free Pascal and Lazarus packages for building desktop applications, tools, and games. It began as a set of general purpose units shared between projects and has grown into a complete toolkit, covering everything from string handling and JSON parsing to antialiased vector graphics, custom controls, OpenGL rendering, 2D physics, audio, an embedded terminal, a web browser control, and controls built from Windows Explorer.
The library is written in Delphi mode. Linux with the GTK3 widgetset is its primary platform, Windows is supported throughout, and the core and graphics units also work on macOS. It is released under the GNU General Public License, version 3.
This document is a tour of the library. It explains how the packages fit together, what each one is for, and which ones you need for the kind of program you want to write. Each package has its own README with examples, and each unit has a text file beside it with the same name, for when you want the details.
## How the Library Is Organized
The library is split into packages so your program only pulls in what it uses. The most important line in that split is between code that needs the LCL and code that doesn't. The core of the library, and the whole rendering engine, can be used without the LCL at all, so a command line tool or a full screen SDL game never has to carry the weight of a form designer it doesn't use.
You can think of the packages as layers, each one built on the ones beneath it:
```
codebot the core, which needs only LazUtils
├── codebot_controls LCL controls and 2D vector graphics
│ ├── codebot_webkit a web browser control
│ └── codebot_render_controls
├── codebot_render OpenGL rendering, scenes, widgets, physics, audio
│ ├── codebot_render_controls runs scenes inside an LCL form
│ └── codebot_render_sdl runs scenes in an SDL window
├── codebot_terminal a terminal emulator control
├── codebot_themes themes for every window of a program
└── codebot_windows_shell controls built from Windows Explorer
```
Alongside these runtime packages are the design time packages, whose names end in _design, along with codebot_explorer. They add components, editors, and tools to the Lazarus IDE, and you never use them in the programs you build.
## The Core: codebot
Every other package is built on [codebot](codebot), and it is the package you will use most. It requires nothing but LazUtils, so you can use it in any kind of program.
At its heart is Codebot.System, which holds the types and routines the rest of the library is written in. Float is the floating point type used everywhere, and TArrayList<T> extends dynamic arrays so they can sort, search, and filter their items. You also get routines for strings, files, math, and time, helpers that add methods to strings and numbers, delegates that let an event have any number of subscribers, and the building blocks of threading, such as mutexes, events, threads, and asynchronous tasks. Codebot.Collections adds generic lists and dictionaries for when an array list is not enough.
The package handles text and data too. Codebot.Text.Json reads, builds, and writes JSON, and Codebot.Text.Xml does the same for XML, using libxml2 on Linux and macOS and MSXML on Windows. Codebot.Text gives you UTF-8 routines and hexadecimal and base64 encoding, and Codebot.Cryptography computes MD5, SHA1, SHA256, and SHA512 hashes.
For math there is Codebot.Geometry, with vectors, matrices, quaternions, and bezier curves for 2D and 3D, and Codebot.Animation, which moves values toward their targets over time using easings.
Networking is covered by Codebot.Networking, whose TSocket can be secured with OpenSSL, and by the units built on it for HTTP requests, FTP, and S3 compatible cloud storage.
Finally, codebot declares the interfaces other packages implement. Codebot.Graphics.Types describes 2D drawing, with surfaces, pens, brushes, fonts, paths, and bitmaps, and Codebot.Platform describes what a program needs from the system it runs on, such as the clipboard, windows, and file dialogs. Because these are only interfaces, code you write against them works the same no matter which package provides them.
## Controls and Vector Graphics: codebot_controls
The [codebot_controls](codebot_controls) package brings the library to the LCL. Its most important unit is Codebot.Graphics, which implements the drawing interfaces of codebot using Cairo on Linux, Direct2D on Windows, and Quartz on macOS. The result is a single drawing API, ISurface, that gives you antialiased vector graphics on every platform.
The controls in this package are drawn using that API rather than the native widgets of the platform, which gives them a consistent look and lets them be themed. You get color pickers, slide bars and slide edits, flat buttons, banners, scrolling lists with column headers, content grids, sizing panels, step indicators, and animated progress icons. The base classes TSurfaceGraphicControl, TSurfaceCustomControl, and TSurfaceForm make it easy to write controls of your own that draw on a surface in the same way.
There are also specialized forms, such as floating forms that can be transparent, popup forms for drop down lists, desktop widgets the user can move and resize, and an advanced color dialog. Smaller units capture system wide hotkeys, monitor the mouse anywhere on the screen, and send debug messages from a running program to another program.
## Graphics and Games: codebot_render
The [codebot_render](codebot_render) package is a cross platform graphics and game engine drawn using OpenGL. Like the core, it does not depend on the LCL, and this is a deliberate part of its design. The same scene can run inside a form of a desktop application or in a full screen SDL window, without changing a line of its code.
Rendering starts with Codebot.OpenGL, which declares OpenGL from version 3.0 to 4.6 and OpenGL ES from 2.0 to 3.2, with the version chosen by a define in render.inc. On top of that, a render context owns the shaders, textures, vertex buffers, and fonts your program creates, and frees whatever your program forgets to.
For 2D drawing, Codebot.Render.Graphics gives you a canvas built on a Pascal port of NanoVG, with paths, gradients, images, sprites, and text. There are also Pascal ports of fontstash and stb_truetype for rendering text, and an SVG reader that draws documents on the canvas.
A program written with codebot_render is made of scenes. A scene draws each frame and handles keyboard and mouse input, and can be stepped at a fixed rate on its own thread. A widget scene adds a complete user interface drawn on the canvas, with windows, buttons, edits, lists, sliders, and file dialogs, styled by a choice of themes ranging from a flat dark look to classic Windows 95. A physics scene adds a 2D physics world powered by Chipmunk2D, which Codebot.Physics wraps in easy to use records.
Codebot.Hardware rounds out the package by playing audio and reading the keyboard, mouse, and joysticks through SDL. It plays MP3, Ogg Vorbis, WAV, and tracker music, all mixed together on the audio thread.
### Choosing a Host
A scene needs a host to give it a window, and the library gives you two. Choose the one that suits your program:
| Host package | Use it when | Your scene runs in |
| --- | --- | --- |
| [codebot_render_controls](codebot_render_controls) | You are writing a desktop application and want OpenGL graphics inside a form, alongside regular controls. | A TGraphicsBox control, managed by a TSceneController. |
| [codebot_render_sdl](codebot_render_sdl) | You are writing a game or a full screen program and don't need the LCL. | An SDL window, managed by the global Application. |
Both hosts give your scene the same canvas, fonts, input, clipboard, and dialogs, so moving a scene from one host to the other is simply a matter of changing which package your program uses.
## A Terminal, a Web Browser, and Windows Explorer
Three more packages each give you a larger control.
The [codebot_terminal](codebot_terminal) package gives you TTerminal, a terminal emulator that runs the user's shell inside your form. It uses VTE, the library of the GNOME terminal, so it works with the GTK2 and GTK3 widgetsets. Its design time package also adds a Terminal window to the Lazarus IDE itself.
The [codebot_webkit](codebot_webkit) package gives you TWebBrowser, a web browser control that embeds WebKitGTK on Linux and Microsoft Edge WebView2 on Windows. It can load pages and HTML, run JavaScript, handle downloads, and show the developer tools, and it comes with an address bar and a status indicator. The browser engine is loaded when your program starts rather than linked when it is built, so a program that uses the browser still runs, and can say so, on a computer where the engine is not installed.
The [codebot_windows_shell](codebot_windows_shell) package gives you controls built from the parts of Windows Explorer itself: a folder view, a folder tree, an address bar, and a preview pane, which you can bind together into a working file browser. It also gives you components that copy and move files with the Windows progress dialog, watch folders for changes, and read and write shortcuts. It is for Windows only.
## Tools for the IDE
A few packages exist only to make the Lazarus IDE nicer to work in:
- [codebot_themes](codebot_themes) themes every window of the programs you build, with the TThemeManager component, on Windows and with the GTK3 widgetset.
- [codebot_themes_design](codebot_themes_design) themes every window of the IDE and lets you choose the color scheme and font of the source editor, on Windows and with the GTK3 widgetset.
- [codebot_explorer](codebot_explorer) adds the Application Explorer, which browses the components of the running IDE and edits their properties.
- [codebot_frame_design](codebot_frame_design) turns a form or frame you designed into a new control on the component palette.
- [codebot_render_sdl_design](codebot_render_sdl_design) adds the Codebot rendering project to the new project dialog.
## Which Packages Do You Need?
| If you are writing | Use these packages |
| --- | --- |
| A command line tool or a service | codebot |
| A desktop application | codebot and codebot_controls |
| A desktop application with OpenGL graphics | codebot, codebot_controls, codebot_render, and codebot_render_controls |
| A game or a full screen program without the LCL | codebot, codebot_render, and codebot_render_sdl |
| A desktop application with a terminal | codebot and codebot_terminal |
| A desktop application with a web browser | codebot, codebot_controls, and codebot_webkit |
| A Windows application with Explorer views | codebot and codebot_windows_shell |
## Libraries the Packages Rely On
Most of the library is plain Pascal, but some features are built on well known libraries. The interop units that declare them are only loaded or linked by the packages that need them.
| Library | Used for | Package |
| --- | --- | --- |
| OpenSSL | Secure sockets | codebot |
| libxml2 | XML documents on Linux and macOS | codebot |
| MSXML | XML documents on Windows | codebot |
| Cairo and GTK | Vector graphics on Linux | codebot_controls |
| Direct2D and WIC | Vector graphics and images on Windows | codebot_controls |
| Core Graphics, Core Text, and ImageIO | Vector graphics and images on macOS | codebot_controls |
| SDL2 and SDL2_image | Windows, OpenGL contexts, input, audio, and images | codebot_render |
| Chipmunk2D | 2D physics, linked statically | codebot_render |
| minimp3, vorbisfile, and libxmp | Decoding audio, linked statically from libcodebotaudio.a | codebot_render |
| assimp | Loading 3D models | codebot_render |
| libmpv | Playing video, when videowidget is defined in render.inc | codebot_render |
| VTE | The terminal emulator | codebot_terminal |
| WebKitGTK | The web browser on Linux | codebot_webkit |
| WebView2 | The web browser on Windows | codebot_webkit |
## A Few Conventions
Every unit of the library includes codebot.inc, which sets Delphi mode, turns on macros, and defines the calling convention of the platform. The rendering packages also include render.inc, which chooses the OpenGL version and turns optional features, such as the video widget, on or off.
Programs that use the library should list Codebot.System first in their uses clause, in place of the cthreads block Lazarus generates. Codebot.System brings in the thread manager on Unix before any other unit starts, which the render thread, the step threads, and queued calls to the main thread all depend on.
## The Packages
| Package | Description | Requires | Kind |
| --- | --- | --- | --- |
| [codebot](codebot) | The core of the library: basic types, collections, text and data formats, geometry, animation, networking, and the interfaces for graphics and the platform. | LazUtils | Runtime |
| [codebot_controls](codebot_controls) | LCL controls and forms that draw themselves using antialiased vector graphics, and the graphics backends for Linux, Windows, and macOS. | codebot, LCL | Runtime |
| [codebot_controls_design](codebot_controls_design) | Adds the components of codebot_controls to the IDE, along with their editors and two new kinds of form. | codebot_controls, IDEIntf | Design time |
| [codebot_explorer](codebot_explorer) | Adds the Application Explorer to the IDE, which browses the components of the IDE and edits their properties. | IDEIntf, RunTimeTypeInfoControls | Design time |
| [codebot_frame_design](codebot_frame_design) | Turns a form or frame of the form designer into a new control whose layout is created in code, and adds it to a new or existing package. | IDEIntf | Design time |
| [codebot_render](codebot_render) | A cross platform graphics and game engine drawn using OpenGL, with scenes, widgets, physics, audio, and input. | codebot | Runtime |
| [codebot_render_controls](codebot_render_controls) | The LCL host of codebot_render, which runs scenes inside a TGraphicsBox on a form. | codebot_render, codebot_controls, LCL | Runtime |
| [codebot_render_design](codebot_render_design) | Adds TGraphicsBox to the IDE. | codebot_render_controls | Design time |
| [codebot_render_sdl](codebot_render_sdl) | The SDL host of codebot_render, which runs scenes in an SDL window without the LCL. | codebot_render | Runtime |
| [codebot_render_sdl_design](codebot_render_sdl_design) | Adds the Codebot rendering project to the new project dialog of the IDE. | IDEIntf | Design time |
| [codebot_terminal](codebot_terminal) | TTerminal, a terminal emulator control built on VTE. | codebot, LCL | Runtime |
| [codebot_terminal_design](codebot_terminal_design) | Adds TTerminal to the IDE, along with a Terminal window inside the IDE. | codebot_terminal, IDEIntf | Design time |
| [codebot_themes](codebot_themes) | TThemeManager, which themes every window of a program with themes stored in its form, and the units that apply themes on Windows and with GTK3. | codebot, LCL | Runtime |
| [codebot_themes_design](codebot_themes_design) | Themes every window of the IDE and chooses the color scheme and font of the source editor, from the Tools menu, and adds TThemeManager to the component palette. Themes are loaded from JSON files, and work on Windows and with GTK3. | codebot_themes, IDEIntf | Design time |
| [codebot_webkit](codebot_webkit) | TWebBrowser, a web browser control built on WebKitGTK and WebView2, with an address bar, a status indicator, and an inspector. | codebot_controls, LCL | Runtime |
| [codebot_webkit_design](codebot_webkit_design) | Adds the web browser controls to the IDE. | codebot_webkit | Design time |
| [codebot_windows_shell](codebot_windows_shell) | Controls built from Windows Explorer, along with file operations, change notifications, and shortcuts. Windows only. | codebot, LCL | Runtime |
| [codebot_windows_shell_design](codebot_windows_shell_design) | Adds the Windows shell components to the IDE, along with a path editor and a binding editor. | codebot_windows_shell, IDEIntf | Design time |