mirror of
https://github.com/RGBCube/serenity
synced 2025-05-14 06:14:58 +00:00
Documentation: Better file formats documentation
This commit is contained in:
sfdd
Linus Groh
parent
b8cfec7b1f
commit
d1671d4f86
5 changed files with 184 additions and 16 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
21
Base/usr/share/man/man5/ini.md
Normal file
21
Base/usr/share/man/man5/ini.md
Normal file
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
29
Base/usr/share/man/man5/pp.md
Normal file
29
Base/usr/share/man/man5/pp.md
Normal file
|
|
@ -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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue