diff options
Diffstat (limited to 'Base/usr/share')
| -rw-r--r-- | Base/usr/share/man/man5/af.md | 39 | ||||
| -rw-r--r-- | Base/usr/share/man/man5/font.md | 32 | ||||
| -rw-r--r-- | Base/usr/share/man/man5/ini.md | 21 | ||||
| -rw-r--r-- | Base/usr/share/man/man5/ipc.md | 79 | ||||
| -rw-r--r-- | Base/usr/share/man/man5/pp.md | 29 |
5 files changed, 184 insertions, 16 deletions
diff --git a/Base/usr/share/man/man5/af.md b/Base/usr/share/man/man5/af.md index d0bf5756ad..e7ba9f803d 100644 --- a/Base/usr/share/man/man5/af.md +++ b/Base/usr/share/man/man5/af.md @@ -1,6 +1,6 @@ ## Name -af - Application File format +af - Application File format (.af) ## Synopsis @@ -8,11 +8,40 @@ The Application Files define System Menu entries and launcher file types / proto ## Description -.af files are human-readable and are a subset of the INI-format, have no easily detectable filemagic. These files define System Menu entries and launcher file types / protocols. +Application files are a subset of the INI format. +They have no easily detectable filemagic and contain application information (App group): -They are stored in [`/res/apps`](../../../../res/apps). +| Key | Description | +|---------------|----------------------------------| +| Name | name | +| Executable | executable path | +| Category | category (optional) | +| Description | description (optional) | +| IconPath | application icon path (optional) | +| RunInTerminal | run in terminal flag (optional) | -## See Also +and launcher information (Launcher group, optional): +| Key | Description | +|-----------|---------------------------------------| +| FileTypes | supported file types separated by ',' | +| Protocols | protocols separated by ',' | + +All application files are stored in [`/res/apps`](../../../../res/apps). + +## Examples + +[`/res/apps/Calendar.af`](../../../../res/apps/Calendar.af) + +```ini +[App] +Name=Calendar +Executable=/bin/Calendar +Category=Utilities +``` + +## See also + +- [ini(5)](help://man/5/ini) - [`Userland/Services/Taskbar/main.cpp`](../../../../../Userland/Services/Taskbar/main.cpp) -- `Launcher::load_handlers` in [`Userland/Services/LaunchServer/Launcher.cpp`](../../../../../Userland/Services/LaunchServer/Launcher.cpp). +- `Launcher::load_handlers` in [`Userland/Services/LaunchServer/Launcher.cpp`](../../../../../Userland/Services/LaunchServer/Launcher.cpp) diff --git a/Base/usr/share/man/man5/font.md b/Base/usr/share/man/man5/font.md index 272336b111..ed1a2fe008 100644 --- a/Base/usr/share/man/man5/font.md +++ b/Base/usr/share/man/man5/font.md @@ -1,17 +1,39 @@ ## Name -font - Bitmap Font File format +font - Bitmap Font File format (.font) ## Synopsis -The .font file format stores bitmap fonts in SerenityOS's own binary format. +Font files contain bitmap definitions of fonts (`Gfx::BitmapFont`). ## Description -These files contain bitmap definitions of fonts, either varying-width or fixed-width. +Bitmap fonts can be either varying-width or fixed-width. +The first four bytes of font files contain the filemagic: `!Fnt` (0x21466e74). -The first four bytes contain the filemagic: `!Fnt` (0x21466e74). +In addition, `Gfx::BitmapFont` supports reading from and writing to font files (as well as reading directly from memory) +and the question mark '?' used as a fallback for unknown glyphs or emojis. + +## Structure + +The order is big-endian. + +| Size | Member name | +|------------|---------------------| +| 4 bytes | Filemagic | +| 1 byte | Glyph width | +| 1 byte | Glyph height | +| 2 bytes | Range mask size | +| 1 byte | Variable width flag | +| 1 byte | Glyph spacing | +| 1 byte | Baseline | +| 1 byte | Mean line | +| 1 byte | Presentation size | +| 2 bytes | Weight | +| 1 byte | Slope | +| 32 bytes | Name | +| 32 bytes | Family | ## See also -- Format header definition in `Gfx::FontFileHeader` in [`Userland/Libraries/LibGfx/Font/BitmapFont.cpp`](../../../../../Userland/Libraries/LibGfx/Font/BitmapFont.cpp). +- Format header definition in `Gfx::FontFileHeader` in [`Userland/Libraries/LibGfx/Font/BitmapFont.cpp`](../../../../../Userland/Libraries/LibGfx/Font/BitmapFont.cpp) diff --git a/Base/usr/share/man/man5/ini.md b/Base/usr/share/man/man5/ini.md new file mode 100644 index 0000000000..a64bf36b13 --- /dev/null +++ b/Base/usr/share/man/man5/ini.md @@ -0,0 +1,21 @@ +## Name + +INI - generic config file format (.ini) + +## Description + +INI files serve as human-readable configuration files. + +They consist of key-value pairs separated by '=', optionally located under a unique group in square brackets. + +Additionally, [`Userland/Libraries/LibCore/ConfigFile.cpp`](../../../../../Userland/Libraries/LibCore/ConfigFile.cpp) +supports comments: the characters '#' and ';' skip the entire line only if they appear at the beginning of the line. + +## Examples + +[`/etc/Keyboard.ini`](../../../../etc/Keyboard.ini) + +```ini +[Mapping] +Keymaps=en-us +``` diff --git a/Base/usr/share/man/man5/ipc.md b/Base/usr/share/man/man5/ipc.md index 8dd375343a..33163309e5 100644 --- a/Base/usr/share/man/man5/ipc.md +++ b/Base/usr/share/man/man5/ipc.md @@ -1,6 +1,6 @@ ## Name -ipc - Inter Process Communication endpoint definition format +IPC - Inter-Process Communication endpoint definition format (.ipc) ## Synopsis @@ -8,10 +8,77 @@ The IPC format of SerenityOS is a domain-specific language (DSL) used to define ## Description -These files are human-readable, have no easily detectable filemagic, and define IPC interfaces. -The format is loosely inspired by C++ headers. +Informally, IPC files - with the help of the IPC compiler - are used to generate message classes that will wrap messages +for interprocess communication in the system. IPC syntax is loosely inspired by C++ headers. Generated IPC message +classes support encode and decode functions to pass messages between the processes. -## See Also +Every IPC pair in the system has a client endpoint and a server endpoint that are described in the IPC files. +Each IPC endpoint should have a unique hashable name that will uniquely identify endpoints in the system. -- [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/). -- [ipc(4)](help://man/4/ipc) (IPC Unix socket documentation) +There are 2 types of APIs that are supported by the IPC files: synchronous and asynchronous. +Synchronous function calls always wait for a response from the other side, while the asynchronous counterparts do not. +In other words, in case of the synchronous calls, the IPC library will not return until it has a response for a caller. + +Ideally, all APIs for the server endpoint should be asynchronous. + +## Examples + +To create a new connection, you first need to generate client and server endpoints. +These endpoints should implement the communication logic using the IPC compiler-generated API messages. + +Start from defining an endpoint in the IPC file in `MyServer.ipc`. + +``` +endpoint MyServer +{ + SyncAPI(String text) => (i32 status) + AsyncAPI(i32 mode) =| +} +``` + +Part of the generated C++ messages: + +```cpp +class SyncAPI final : public IPC::Message { +public: + using ResponseType = SyncAPIResponse; + SyncAPI(const String& text) : m_text(text) {} + virtual ~SyncAPI() override {} + static OwnPtr<SyncAPI> decode(...); + virtual IPC::MessageBuffer encode(...) const override; +}; +``` + +Then, you need to inherit your connection class from `IPC::ConnectionFromClient` with created server and client +endpoints as template parameters if it is a server connection. Otherwise, your class need to be inherited +from `IPC::ConnectionToServer` with created server and client endpoints as template parameters and from the client +endpoint class. + +Part of the connection implementations: + +```cpp +// Server side. +namespace MyServer { + +class ConnectionFromClient final + : public IPC::ConnectionFromClient<MyClientEndpoint, MyServerEndpoint> {}; + +} + +// Client side. +namespace MyClient { + + class Client final + : public IPC::ConnectionToServer<MyClientEndpoint, MyServerEndpoint> + , public MyClientEndpoint {}; + +} +``` + +Note, there are two types of functions for sending the messages: synchronous and asynchronous. The generated +asynchronous functions are prefixed with `async_` and the names of the synchronous functions are not changed. + +## See also + +- [`Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp`](../../../../../Meta/Lagom/Tools/CodeGenerators/IPCCompiler/main.cpp) +- [ipc(4)](help://man/4/ipc) (IPC Unix socket documentation) diff --git a/Base/usr/share/man/man5/pp.md b/Base/usr/share/man/man5/pp.md new file mode 100644 index 0000000000..b890a0efd4 --- /dev/null +++ b/Base/usr/share/man/man5/pp.md @@ -0,0 +1,29 @@ +## Name + +PP - Pixel Paint application file format (.pp) + +## Description + +Pixel Paint files store the drawing data produced by the Pixel Paint application. + +This is a rough overview of the contents of the files: + +- width +- height +- layers (optional) + - width + - height + - name + - locationx + - locationy + - opacity_percent + - visible + - selected + - bitmap +- guides (optional) + - offset + - orientation + +## See also + +- [`Userland/Applications/PixelPaint/Image.cpp`](../../../../../Userland/Applications/PixelPaint/Image.cpp) |