docs/develop: reorganize app_server documentation
Separate the "interface specification" into multiple individual, shorter pages. Also update some outdated parts and replace references to OpenBeOS with Haiku. Change-Id: I86baa9a78c5f7a8a3c4c7aa3ac2992714afecae6 Reviewed-on: https://review.haiku-os.org/c/haiku/+/6084 Tested-by: Automation <[email protected]> Reviewed-by: Adrien Destugues <[email protected]>
This commit is contained in:
PulkoMandy
committed by
Adrien Destugues
Adrien Destugues
parent
b19fa88344
commit
53df6323c8
@@ -1,425 +0,0 @@
|
|||||||
App Server Interface Specification v0.3
|
|
||||||
#######################################
|
|
||||||
|
|
||||||
Purpose:
|
|
||||||
========
|
|
||||||
|
|
||||||
The app_server provides services to the OpenBeOS by managing processes,
|
|
||||||
filtering and dispatching input from the Input Server to the appropriate
|
|
||||||
applications, and managing all graphics-related tasks.
|
|
||||||
|
|
||||||
Tasks:
|
|
||||||
======
|
|
||||||
|
|
||||||
The tasks performed by the app_server are grouped in relation to its
|
|
||||||
purpose.
|
|
||||||
|
|
||||||
- Receives and redirects (dispatches) messages from the input server
|
|
||||||
- Responds to messages from apps
|
|
||||||
- Receives and consolidates requests from BView, BWindow, BBitmap, and others to draw stuff (draw bitmap, etc)
|
|
||||||
- Utilizes ports to communicate with child processes
|
|
||||||
- Handles drag & drop messaging
|
|
||||||
- Manages the system clipboard
|
|
||||||
- Loads and Kills processes
|
|
||||||
- Detects absence of Input Server and restarts when not running
|
|
||||||
- Aids in system shutdown
|
|
||||||
- Dynamically loads accelerant portion of graphics driver
|
|
||||||
- Creates a connection with BBitmaps requiring a child view
|
|
||||||
- Draws the blue desktop screen
|
|
||||||
- Provides workspace support
|
|
||||||
- Provides functionality to the BeAPI for drawing primitives, such as rectangles, ellipses, and beziers
|
|
||||||
- Provides a means for BViews to draw on BBitmaps
|
|
||||||
- Manages window behavior with respect to redraw (move to front, minimize, etc)
|
|
||||||
- Returns a frame buffer to direct-access classes
|
|
||||||
- Caches fonts for screen and printer use
|
|
||||||
- Draws text and provides other font API support for the BeAPI classes
|
|
||||||
|
|
||||||
Graphics:
|
|
||||||
=========
|
|
||||||
|
|
||||||
Desktop Initialization
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
The graphics hardware is abstracted from the rest of the app_server.
|
|
||||||
When started, the server creates the desktop, which is little more than
|
|
||||||
a collection of workspaces. The desktop actually creates a DisplayDriver
|
|
||||||
and then calls the driver's method Inititialize() before calling a few
|
|
||||||
high-level routines for setup. Below is the process by which the
|
|
||||||
HWDriver class, which is used to access the primary graphics card in the
|
|
||||||
system, followed by the steps taken to set up the desktop.
|
|
||||||
|
|
||||||
Load Accelerant
|
|
||||||
...............
|
|
||||||
|
|
||||||
The app_server looks in three paths when scanning for an accelerant:
|
|
||||||
|
|
||||||
- /fd/beos/system/add-ons/app_server
|
|
||||||
- /boot/home/config/add-ons/app_server
|
|
||||||
- /boot/beos/system/add-ons/app_server
|
|
||||||
|
|
||||||
When the app_server searches a path, it simply prints to the debug
|
|
||||||
stream on the serial port a message akin "Attempting to load accelerant
|
|
||||||
so-and-so" when loading the accelerant. Following this, it is loads the
|
|
||||||
accelerant via load_add_on(), obtains the hook function
|
|
||||||
control_graphics_card is via get_image_symbol, and
|
|
||||||
control_graphics_card(OPEN_GRAPHICS_CARD) is called. If this returns an
|
|
||||||
error, the image is unloaded after a
|
|
||||||
control_graphics_card(CLOSE_GRAPHICS_CARD) is called and the server
|
|
||||||
spits out a message like "So-and-so is not an acceptable driver" to the
|
|
||||||
serial port. Assuming that the OPEN call succeeds, the app_server serial
|
|
||||||
prints "Using so-and-so as accelerant." Hook functions are then acquired
|
|
||||||
through control_graphics_card(B_GET_GRAPHICS_CARD_HOOKS). At this point,
|
|
||||||
it is a good idea to have a palette generated for 8-bit mode (just in
|
|
||||||
case we're going to use it), so the server generates the system palette.
|
|
||||||
The palette on the graphics card is then set through many calls to
|
|
||||||
control_graphics_card(B_SET_INDEXED_COLOR).
|
|
||||||
|
|
||||||
Set up workspaces
|
|
||||||
.................
|
|
||||||
|
|
||||||
Workspace preferences are read in from disk. If they exist, they are
|
|
||||||
used; otherwise the default of 3 workspace, each with the settings
|
|
||||||
[email protected], is used. Each workspace is initialized to the proper
|
|
||||||
information (preferences or default). Additionally, all settings are
|
|
||||||
checked and possibly "clipped" by information gained through the driver
|
|
||||||
class. With the desktop having been given the proper settings, the
|
|
||||||
default workspace, 0, is activated.
|
|
||||||
|
|
||||||
Display
|
|
||||||
.......
|
|
||||||
|
|
||||||
Provided that everything has gone well so far, the screen is filled to
|
|
||||||
the user-set workspace color or RGB(51,102,160) Also, the global
|
|
||||||
clipboard is created, which is nothing more than a BClipboard object.
|
|
||||||
The Input Server will notify the app_server of its existence, at which
|
|
||||||
point the cursor will be set to B_HAND_CURSOR and shown on the screen.
|
|
||||||
|
|
||||||
Window management
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
Window management is a complicated issue, requiring the cooperation of a
|
|
||||||
number of different types of elements. Each BApplication, BWindow, and
|
|
||||||
BView has a counterpart in the app_server which has a role to play.
|
|
||||||
These objects are Decorators, ServerApps, ServerWindows, Layers, and
|
|
||||||
WindowBorders.
|
|
||||||
|
|
||||||
ServerApps
|
|
||||||
..........
|
|
||||||
|
|
||||||
ServerApp objects are created when a BApplication notifies the
|
|
||||||
app_server of its presence. In acknowledging the BApplication's
|
|
||||||
existence, the server creates a ServerApp which will handle future
|
|
||||||
server-app communications and notifies the BApplication of the port to
|
|
||||||
which it must send future messages.
|
|
||||||
|
|
||||||
ServerApps are each an independent thread which has a function similar
|
|
||||||
to that of a BLooper, but with additional tasks. When a BWindow is
|
|
||||||
created, it spawns a ServerWindow object to handle the new window. The
|
|
||||||
same applies to when a window is destroyed. Cursor commands and all
|
|
||||||
other BApplication functions which require server interaction are also
|
|
||||||
handled. B_QUIT_REQUESTED messages are received and passed along to the
|
|
||||||
main thread in order for the ServerApp object to be destroyed. The
|
|
||||||
server's Picasso thread also utilizes ServerApp::PingTarget in order to
|
|
||||||
determine whether the counterpart BApplication is still alive and
|
|
||||||
running.
|
|
||||||
|
|
||||||
ServerWindows
|
|
||||||
.............
|
|
||||||
|
|
||||||
ServerWindow objects' purpose is to take care of the needs of BWindows.
|
|
||||||
This includes all calls which require a trip to the server, such as
|
|
||||||
BView graphics calls and sending messages to invoke hook functions
|
|
||||||
within a window.
|
|
||||||
|
|
||||||
Layers
|
|
||||||
......
|
|
||||||
|
|
||||||
Layers are shadowed BViews and are used to handle much BView
|
|
||||||
functionality and also determine invalid screen regions. Hierarchal
|
|
||||||
functions, such as AddChild, are mirrored. Invalid regions are tracked
|
|
||||||
and generate Draw requests which are sent to the application for a
|
|
||||||
specific BView to update its part of the screen.
|
|
||||||
|
|
||||||
WindowBorders
|
|
||||||
.............
|
|
||||||
|
|
||||||
WindowBorders are a special kind of Layer with no BView counterpart,
|
|
||||||
designed to handle window management issues, such as click tests, resize
|
|
||||||
and move events, and ensuring that its decorator updates the screen
|
|
||||||
appropriately.
|
|
||||||
|
|
||||||
Decorators
|
|
||||||
..........
|
|
||||||
|
|
||||||
Decorators are addons which are intended to do one thing: draw the
|
|
||||||
window frame. The Decorator API and development information is described
|
|
||||||
in the Decorator Development Reference. They are essentially the means
|
|
||||||
by which WindowBorders draw to the screen.
|
|
||||||
|
|
||||||
How It All Works
|
|
||||||
................
|
|
||||||
|
|
||||||
The app_server is one large, complex beast because of all the tasks it
|
|
||||||
performs. It also utilizes the various objects to accomplish them. Input
|
|
||||||
messages are received from the Input Server and all messages not
|
|
||||||
specific to the server (such as Ctrl-Alt-Shift-Backspace) are passed to
|
|
||||||
the active application, if any. Mouse clicks are passed to the
|
|
||||||
ServerWindow class for hit testing. These hit tests can result in window
|
|
||||||
tabs and buttons being clicked, or mouse click messages being passed to
|
|
||||||
a specific view in a window.
|
|
||||||
|
|
||||||
These input messages which are passed to a running application will
|
|
||||||
sometimes cause things to happen inside it, such as button presses,
|
|
||||||
window closings/openings, etc. which will cause messages to be sent to
|
|
||||||
the server. These messages are sent either from a BWindow to a
|
|
||||||
ServerWindow or a BApplication to a ServerApp. When such messages are
|
|
||||||
sent, then the corresponding app_server object performs an appropriate
|
|
||||||
action.
|
|
||||||
|
|
||||||
Screen Updates
|
|
||||||
--------------
|
|
||||||
|
|
||||||
Screen updates are done entirely through the BView class or some
|
|
||||||
subclass thereof, hereafter referred to as a view. A view's drawing
|
|
||||||
commands will cause its window to store draw command messages in a
|
|
||||||
message packet. At some point Flush() will be called and the command
|
|
||||||
packet will be sent to the window's ServerWindow object inside the
|
|
||||||
server.
|
|
||||||
|
|
||||||
The ServerWindow will receive the packet, check to ensure that its size
|
|
||||||
is correct, and begin retrieving each command from the packet and
|
|
||||||
dispatching it, taking the appropriate actions. Actual drawing commands,
|
|
||||||
such as StrokeRect, will involve the ServerWindow object calling the
|
|
||||||
appropriate command in the graphics module for the Layer corresponding
|
|
||||||
to the view which sent the command.
|
|
||||||
|
|
||||||
Cursor Management
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
The app_server handles all messiness to do with the cursor. The cursor
|
|
||||||
commands which are members of the BApplication class will send a message
|
|
||||||
to its ServerApp, which will then call the DisplayDriver's appropriate
|
|
||||||
function. The DisplayDriver used will actually handle the drawing of the
|
|
||||||
cursor and whether or not to do so at any given time.
|
|
||||||
|
|
||||||
OpenBeOS R1 will also include the advent of an extension of the API:
|
|
||||||
SetCursor(BBitmap \*), which will accept a BBitmap of color space
|
|
||||||
RGB(A)32, RGBA16, CMAP8, GRAY8, or GRAY1. Thus, color cursors and
|
|
||||||
cursors which are not 16x16 are now supported.
|
|
||||||
|
|
||||||
Display Drivers
|
|
||||||
---------------
|
|
||||||
|
|
||||||
Unlike the BeOS R5 app_server, OpenBeOS' server will have a special
|
|
||||||
feature: a modular graphics driver access class. The class is not
|
|
||||||
actually the graphics driver, but, rather, a generalized interface which
|
|
||||||
is implemented to interact with various destinations for graphics
|
|
||||||
output. This allows the server to draw to a BWindow/BView combination, a
|
|
||||||
BDirectWindow, or the actual frame buffer of a particular graphics card.
|
|
||||||
All that the rest of the server needs to do is call whichever graphics
|
|
||||||
function that is needed.
|
|
||||||
|
|
||||||
Process Management
|
|
||||||
==================
|
|
||||||
|
|
||||||
BApplication execution
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
Applications will come in two types: those which communicate with the
|
|
||||||
app_server and take advantage of its services, and those which do not.
|
|
||||||
To access the app_server, an application must be derived from
|
|
||||||
BApplication.
|
|
||||||
|
|
||||||
When a BApplication (referred to hereafter as a BApp) is executed, the
|
|
||||||
app constructor creates its BLooper message port with the name
|
|
||||||
AppLooperPort. This port's id, by means of BLooper, registers its
|
|
||||||
port_id with the app_server so that the two can communicate with each
|
|
||||||
other most easily.
|
|
||||||
|
|
||||||
When the app_server receives notification that an app has been created,
|
|
||||||
the server creates an AppMonitor (with accompanying thread) in its own
|
|
||||||
team to handle messages sent to it and sends a reply with the port_id of
|
|
||||||
the AppMonitor, to which all future messages are sent. These AppMonitor
|
|
||||||
objects are stored in a global BList created for the storage of such
|
|
||||||
things.
|
|
||||||
|
|
||||||
non-BApplication execution
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
Other applications do not communicate with the app_server. These
|
|
||||||
applications have no access to app services and do not generally pass
|
|
||||||
BMessages. This includes, but is not limited to, UNIX apps. The
|
|
||||||
app_server ignores such applications except when asked to kill them.
|
|
||||||
|
|
||||||
While, technically, these are not limited to being non-GUI applications,
|
|
||||||
in practice these applications are command-line-only, for the
|
|
||||||
application would be required to (1) render the app_server unable to
|
|
||||||
access video hardware and (2) reinvent existing graphics code to load
|
|
||||||
and use accelerants and draw onto the video buffer. This is extremely
|
|
||||||
bad style and programming practice, not to mention more work than it is
|
|
||||||
worth except in one case: the OpenBeOS app_server can coexist with the
|
|
||||||
BeOS R5 app_server with some degree of peace because it can utilize
|
|
||||||
extra video cards which the BeOS app_server does not use.
|
|
||||||
|
|
||||||
Killing/Exiting Applications
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
While the input server handles the Team Monitor window, the app_server
|
|
||||||
actually takes care of shutting down teams, peacefully or not. Exiting
|
|
||||||
an app is done simply by sending a B_QUIT_REQUESTED message to
|
|
||||||
particular app. Killing an app is done via kill_team, but all the messy
|
|
||||||
details are handled by the kernel itself through this call. When the
|
|
||||||
user requests a team die via the Team Monitor, the Input Server sends a
|
|
||||||
message to the app_server to kill the team, attaching the team_id. The
|
|
||||||
app_server responds by happily nuking the respective team and notifies
|
|
||||||
the registrar of its forcible removal from the roster.
|
|
||||||
|
|
||||||
System Shutdown
|
|
||||||
---------------
|
|
||||||
|
|
||||||
Although the server maintains an internal list of running GUI
|
|
||||||
applications, when a request to shut down the system is received by the
|
|
||||||
app_server, it will pass the request on to the registrar, which will, in
|
|
||||||
turn, increment its way through the app roster and request each app
|
|
||||||
quit. When each quit request is sent, a timer is started and after
|
|
||||||
timeout, the registrar will ask the server to kill the particular team
|
|
||||||
and continue iterating through the application list.
|
|
||||||
|
|
||||||
Input Processing
|
|
||||||
================
|
|
||||||
|
|
||||||
Input Server messages
|
|
||||||
---------------------
|
|
||||||
|
|
||||||
The Input Server collects information about keyboard and mouse events
|
|
||||||
and forwards them to the app_server via messages. They are sent to port
|
|
||||||
specifically for such messages, and the port is monitored by a thread
|
|
||||||
whose task is to monitor, process, and dispatch them to the appropriate
|
|
||||||
recipients. The Input Server is a regular BApplication, and unlike other
|
|
||||||
applications, it requests a port to which it can send input messages.
|
|
||||||
|
|
||||||
Mouse
|
|
||||||
-----
|
|
||||||
|
|
||||||
Mouse events consist of button changes, mouse movements, and the mouse
|
|
||||||
wheel. The message will consist of the time of the event and attachments
|
|
||||||
appropriate for each message listed below:
|
|
||||||
|
|
||||||
B_MOUSE_DOWN
|
|
||||||
............
|
|
||||||
|
|
||||||
- when
|
|
||||||
- location of the cursor
|
|
||||||
- button number
|
|
||||||
- modifiers
|
|
||||||
- clicks
|
|
||||||
|
|
||||||
B_MOUSE_UP
|
|
||||||
..........
|
|
||||||
|
|
||||||
- time
|
|
||||||
- buttons' status // not implemented for R5 but included for future expansion
|
|
||||||
- location of the cursor
|
|
||||||
- modifiers
|
|
||||||
|
|
||||||
B_MOUSE_MOVED
|
|
||||||
.............
|
|
||||||
|
|
||||||
- time
|
|
||||||
- location of the cursor
|
|
||||||
- buttons' status
|
|
||||||
|
|
||||||
B_MOUSE_WHEEL_CHANGED
|
|
||||||
.....................
|
|
||||||
|
|
||||||
- time
|
|
||||||
- location of the cursor
|
|
||||||
- transit - in or out
|
|
||||||
- x delta
|
|
||||||
- y delta
|
|
||||||
|
|
||||||
Keyboard
|
|
||||||
--------
|
|
||||||
|
|
||||||
Keyboard events consist of notification when a key is pressed or
|
|
||||||
released. Any keypress or release will evoke a message, regardless of
|
|
||||||
whether or not the key is mapped. The message will consist of the
|
|
||||||
appropriate code and attachments listed below:
|
|
||||||
|
|
||||||
B_KEY_DOWN
|
|
||||||
..........
|
|
||||||
|
|
||||||
- time
|
|
||||||
- key code
|
|
||||||
- repeat count
|
|
||||||
- modifiers
|
|
||||||
- states
|
|
||||||
- UTF-8 code
|
|
||||||
- string generated
|
|
||||||
- modifier-independent ASCII code
|
|
||||||
|
|
||||||
B_KEY_UP
|
|
||||||
........
|
|
||||||
|
|
||||||
- time
|
|
||||||
- key code
|
|
||||||
- modifiers
|
|
||||||
- states
|
|
||||||
- UTF-8 code
|
|
||||||
- string generated
|
|
||||||
- modifier-independent ASCII code
|
|
||||||
|
|
||||||
B_UNMAPPED_KEY_DOWN
|
|
||||||
...................
|
|
||||||
|
|
||||||
- time
|
|
||||||
- key code
|
|
||||||
- modifiers
|
|
||||||
- states
|
|
||||||
|
|
||||||
B_UNMAPPED_KEY_UP
|
|
||||||
.................
|
|
||||||
|
|
||||||
- time
|
|
||||||
- key code
|
|
||||||
- modifiers
|
|
||||||
- states
|
|
||||||
|
|
||||||
B_MODIFIERS_CHANGED
|
|
||||||
...................
|
|
||||||
|
|
||||||
sent when a modifier key changes
|
|
||||||
|
|
||||||
- time
|
|
||||||
- modifier states
|
|
||||||
- previous modifier states
|
|
||||||
- states
|
|
||||||
|
|
||||||
Nearly all keypresses received by the app_server are passed onto the
|
|
||||||
appropriate application. Control-Tab, when held, is sent to the Deskbar
|
|
||||||
for app switching. Command+F?? is intercepted and a workspace is
|
|
||||||
switched. Left Control + Alt + Delete is not even intercepted by the
|
|
||||||
app_server. The Input Server receives it and shows the Team Monitor
|
|
||||||
window.
|
|
||||||
|
|
||||||
Messaging
|
|
||||||
=========
|
|
||||||
|
|
||||||
Inter-Application Messaging
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
The details of messaging are depicted under Process
|
|
||||||
Management::BApplication.
|
|
||||||
|
|
||||||
Drag-and-drop
|
|
||||||
-------------
|
|
||||||
|
|
||||||
Methods
|
|
||||||
-------
|
|
||||||
|
|
||||||
Messaging with the app_server is not done using BMessages because of the
|
|
||||||
overhead required to send them costs time and speed. Instead, ports are
|
|
||||||
utilized indirectly by means of the PortLink class, which simply makes
|
|
||||||
attaching data to a port message easier, but requires very little
|
|
||||||
overhead.
|
|
||||||
|
|
||||||
@@ -0,0 +1,172 @@
|
|||||||
|
Graphics
|
||||||
|
=========
|
||||||
|
|
||||||
|
Desktop Initialization
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
The graphics hardware is abstracted from the rest of the app_server.
|
||||||
|
When started, the server creates the desktop, which is little more than
|
||||||
|
a collection of workspaces. The desktop actually creates a DisplayDriver
|
||||||
|
and then calls the driver's method Inititialize() before calling a few
|
||||||
|
high-level routines for setup. Below is the process by which the
|
||||||
|
HWDriver class, which is used to access the primary graphics card in the
|
||||||
|
system, followed by the steps taken to set up the desktop.
|
||||||
|
|
||||||
|
Load Accelerant
|
||||||
|
...............
|
||||||
|
|
||||||
|
First of all, the available video cards are scanned by enumerating the contents of /dev/graphics.
|
||||||
|
For each device, the B_GET_ACCELERANT_SIGNATURE ioctl is used to find the corresponding accelerant
|
||||||
|
name.
|
||||||
|
|
||||||
|
The app_server looks for an accelerant matching that name in the "accelerants" subdirectory of each
|
||||||
|
add-on directory (enumerated using BPathFinder). The first matching accelerant is loaded
|
||||||
|
using load_add_on(). Then the get_accelerant_hook() function is obtained through get_image_symbol.
|
||||||
|
This is the only needed entry point for the accelerant, and can be used to call all the other
|
||||||
|
needed code, starting with B_INIT_ACCELERANT.
|
||||||
|
|
||||||
|
For more information about the accelerant hooks, see `Writing video card drivers <https://www.haiku-os.org/legacy-docs/writing-video-card-drivers/04-accelerant>`_.
|
||||||
|
|
||||||
|
Set up workspaces
|
||||||
|
.................
|
||||||
|
|
||||||
|
Workspace preferences are read in from disk. If they exist, they are
|
||||||
|
used; otherwise the default of 3 workspace, each with the settings
|
||||||
|
[email protected], is used. Each workspace is initialized to the proper
|
||||||
|
information (preferences or default). Additionally, all settings are
|
||||||
|
checked and possibly "clipped" by information gained through the driver
|
||||||
|
class. With the desktop having been given the proper settings, the
|
||||||
|
default workspace, 0, is activated.
|
||||||
|
|
||||||
|
Display
|
||||||
|
.......
|
||||||
|
|
||||||
|
Provided that everything has gone well so far, the screen is filled to
|
||||||
|
the user-set workspace color or RGB(51,102,160) Also, the global
|
||||||
|
clipboard is created, which is nothing more than a BClipboard object.
|
||||||
|
|
||||||
|
The Input Server will notify the app_server of its own existence, at which
|
||||||
|
point the cursor will be set to B_HAND_CURSOR and shown on the screen.
|
||||||
|
|
||||||
|
Window management
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Window management is a complicated issue, requiring the cooperation of a
|
||||||
|
number of different types of elements. Each BApplication, BWindow, and
|
||||||
|
BView has a counterpart in the app_server which has a role to play.
|
||||||
|
These objects are Decorators, ServerApps, ServerWindows, Layers, and
|
||||||
|
WindowBorders.
|
||||||
|
|
||||||
|
ServerApps
|
||||||
|
..........
|
||||||
|
|
||||||
|
ServerApp objects are created when a BApplication notifies the
|
||||||
|
app_server of its presence. In acknowledging the BApplication's
|
||||||
|
existence, the server creates a ServerApp which will handle future
|
||||||
|
server-app communications and notifies the BApplication of the port to
|
||||||
|
which it must send future messages.
|
||||||
|
|
||||||
|
ServerApps are each an independent thread which has a function similar
|
||||||
|
to that of a BLooper, but with additional tasks. When a BWindow is
|
||||||
|
created, it spawns a ServerWindow object to handle the new window. The
|
||||||
|
same applies to when a window is destroyed. Cursor commands and all
|
||||||
|
other BApplication functions which require server interaction are also
|
||||||
|
handled. B_QUIT_REQUESTED messages are received and passed along to the
|
||||||
|
main thread in order for the ServerApp object to be destroyed. The
|
||||||
|
server's Picasso thread also utilizes ServerApp::PingTarget in order to
|
||||||
|
determine whether the counterpart BApplication is still alive and
|
||||||
|
running.
|
||||||
|
|
||||||
|
ServerWindows
|
||||||
|
.............
|
||||||
|
|
||||||
|
ServerWindow objects' purpose is to take care of the needs of BWindows.
|
||||||
|
This includes all calls which require a trip to the server, such as
|
||||||
|
BView graphics calls and sending messages to invoke hook functions
|
||||||
|
within a window.
|
||||||
|
|
||||||
|
Layers
|
||||||
|
......
|
||||||
|
|
||||||
|
Layers are shadowed BViews and are used to handle much BView
|
||||||
|
functionality and also determine invalid screen regions. Hierarchal
|
||||||
|
functions, such as AddChild, are mirrored. Invalid regions are tracked
|
||||||
|
and generate Draw requests which are sent to the application for a
|
||||||
|
specific BView to update its part of the screen.
|
||||||
|
|
||||||
|
WindowBorders
|
||||||
|
.............
|
||||||
|
|
||||||
|
WindowBorders are a special kind of Layer with no BView counterpart,
|
||||||
|
designed to handle window management issues, such as click tests, resize
|
||||||
|
and move events, and ensuring that its decorator updates the screen
|
||||||
|
appropriately.
|
||||||
|
|
||||||
|
Decorators
|
||||||
|
..........
|
||||||
|
|
||||||
|
Decorators are addons which are intended to do one thing: draw the
|
||||||
|
window frame. The Decorator API and development information is described
|
||||||
|
in the Decorator Development Reference. They are essentially the means
|
||||||
|
by which WindowBorders draw to the screen.
|
||||||
|
|
||||||
|
How It All Works
|
||||||
|
................
|
||||||
|
|
||||||
|
The app_server is one large, complex beast because of all the tasks it
|
||||||
|
performs. It also utilizes the various objects to accomplish them. Input
|
||||||
|
messages are received from the Input Server and all messages not
|
||||||
|
specific to the server (such as Ctrl-Alt-Shift-Backspace) are passed to
|
||||||
|
the active application, if any. Mouse clicks are passed to the
|
||||||
|
ServerWindow class for hit testing. These hit tests can result in window
|
||||||
|
tabs and buttons being clicked, or mouse click messages being passed to
|
||||||
|
a specific view in a window.
|
||||||
|
|
||||||
|
These input messages which are passed to a running application will
|
||||||
|
sometimes cause things to happen inside it, such as button presses,
|
||||||
|
window closings/openings, etc. which will cause messages to be sent to
|
||||||
|
the server. These messages are sent either from a BWindow to a
|
||||||
|
ServerWindow or a BApplication to a ServerApp. When such messages are
|
||||||
|
sent, then the corresponding app_server object performs an appropriate
|
||||||
|
action.
|
||||||
|
|
||||||
|
Screen Updates
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Screen updates are done entirely through the BView class or some
|
||||||
|
subclass thereof, hereafter referred to as a view. A view's drawing
|
||||||
|
commands will cause its window to store draw command messages in a
|
||||||
|
message packet. At some point Flush() will be called and the command
|
||||||
|
packet will be sent to the window's ServerWindow object inside the
|
||||||
|
server.
|
||||||
|
|
||||||
|
The ServerWindow will receive the packet, check to ensure that its size
|
||||||
|
is correct, and begin retrieving each command from the packet and
|
||||||
|
dispatching it, taking the appropriate actions. Actual drawing commands,
|
||||||
|
such as StrokeRect, will involve the ServerWindow object calling the
|
||||||
|
appropriate command in the graphics module for the Layer corresponding
|
||||||
|
to the view which sent the command.
|
||||||
|
|
||||||
|
Cursor Management
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
The app_server handles all messiness to do with the cursor. The cursor
|
||||||
|
commands which are members of the BApplication class will send a message
|
||||||
|
to its ServerApp, which will then call the DisplayDriver's appropriate
|
||||||
|
function. The DisplayDriver used will actually handle the drawing of the
|
||||||
|
cursor and whether or not to do so at any given time.
|
||||||
|
|
||||||
|
In addition to the 1 bit per pixel cursors used in BeOS, Haiku also allows to create a BCursor
|
||||||
|
object from a BBitmap in any colorspace. This allows color cursors and also larger cursor sizes.
|
||||||
|
The default cursors also use greyscale and alpha channel for antialiasing.
|
||||||
|
|
||||||
|
Display Drivers
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Unlike the BeOS R5 app_server, Haiku' server has an extra abstraction layer between the graphic
|
||||||
|
driver and the main drawing functions. This allows to generalize the interface and redirect the
|
||||||
|
drawing commands in various ways. For example, drawing commands can be redirected to another
|
||||||
|
machine for the remote_app_server, or drawing for a specific window can be granted direct access
|
||||||
|
to the framebuffer on a specific display and video card, while other applications go through the
|
||||||
|
normal process of drawing only to their currently exposed region only.
|
||||||
|
|
||||||
@@ -0,0 +1,118 @@
|
|||||||
|
Input Processing
|
||||||
|
================
|
||||||
|
|
||||||
|
Input Server messages
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
The Input Server collects information about keyboard and mouse events
|
||||||
|
and forwards them to the app_server via messages. They are sent to port
|
||||||
|
specifically for such messages, and the port is monitored by a thread
|
||||||
|
whose task is to monitor, process, and dispatch them to the appropriate
|
||||||
|
recipients. The Input Server is a regular BApplication, and unlike other
|
||||||
|
applications, it requests a port to which it can send input messages.
|
||||||
|
|
||||||
|
Mouse
|
||||||
|
-----
|
||||||
|
|
||||||
|
Mouse events consist of button changes, mouse movements, and the mouse
|
||||||
|
wheel. The message will consist of the time of the event and attachments
|
||||||
|
appropriate for each message listed below:
|
||||||
|
|
||||||
|
B_MOUSE_DOWN
|
||||||
|
............
|
||||||
|
|
||||||
|
- when
|
||||||
|
- buttons' status
|
||||||
|
- location of the cursor
|
||||||
|
- modifiers
|
||||||
|
- clicks
|
||||||
|
|
||||||
|
B_MOUSE_UP
|
||||||
|
..........
|
||||||
|
|
||||||
|
- time
|
||||||
|
- buttons' status
|
||||||
|
- location of the cursor
|
||||||
|
- modifiers
|
||||||
|
|
||||||
|
B_MOUSE_MOVED
|
||||||
|
.............
|
||||||
|
|
||||||
|
- time
|
||||||
|
- location of the cursor
|
||||||
|
- buttons' status
|
||||||
|
|
||||||
|
B_MOUSE_WHEEL_CHANGED
|
||||||
|
.....................
|
||||||
|
|
||||||
|
- time
|
||||||
|
- location of the cursor
|
||||||
|
- transit - in or out
|
||||||
|
- x delta
|
||||||
|
- y delta
|
||||||
|
|
||||||
|
Keyboard
|
||||||
|
--------
|
||||||
|
|
||||||
|
Keyboard events consist of notification when a key is pressed or
|
||||||
|
released. Any keypress or release will evoke a message, regardless of
|
||||||
|
whether or not the key is mapped. The message will consist of the
|
||||||
|
appropriate code and attachments listed below:
|
||||||
|
|
||||||
|
B_KEY_DOWN
|
||||||
|
..........
|
||||||
|
|
||||||
|
- time
|
||||||
|
- key code
|
||||||
|
- repeat count
|
||||||
|
- modifiers
|
||||||
|
- states
|
||||||
|
- UTF-8 code
|
||||||
|
- string generated
|
||||||
|
- modifier-independent ASCII code
|
||||||
|
|
||||||
|
B_KEY_UP
|
||||||
|
........
|
||||||
|
|
||||||
|
- time
|
||||||
|
- key code
|
||||||
|
- modifiers
|
||||||
|
- states
|
||||||
|
- UTF-8 code
|
||||||
|
- string generated
|
||||||
|
- modifier-independent ASCII code
|
||||||
|
|
||||||
|
B_UNMAPPED_KEY_DOWN
|
||||||
|
...................
|
||||||
|
|
||||||
|
- time
|
||||||
|
- key code
|
||||||
|
- modifiers
|
||||||
|
- states
|
||||||
|
|
||||||
|
B_UNMAPPED_KEY_UP
|
||||||
|
.................
|
||||||
|
|
||||||
|
- time
|
||||||
|
- key code
|
||||||
|
- modifiers
|
||||||
|
- states
|
||||||
|
|
||||||
|
B_MODIFIERS_CHANGED
|
||||||
|
...................
|
||||||
|
|
||||||
|
sent when a modifier key changes
|
||||||
|
|
||||||
|
- time
|
||||||
|
- modifier states
|
||||||
|
- previous modifier states
|
||||||
|
- states
|
||||||
|
|
||||||
|
Nearly all keypresses received by the app_server are passed onto the
|
||||||
|
appropriate application. Control-Tab, when held, is sent to the Deskbar
|
||||||
|
for app switching. Command+F?? is intercepted and a workspace is
|
||||||
|
switched. Left Control + Alt + Delete is not even intercepted by the
|
||||||
|
app_server. The Input Server receives it and shows the Team Monitor
|
||||||
|
window.
|
||||||
|
|
||||||
|
|
||||||
@@ -0,0 +1,22 @@
|
|||||||
|
Messaging
|
||||||
|
=========
|
||||||
|
|
||||||
|
Inter-Application Messaging
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
The details of messaging are depicted under Process
|
||||||
|
Management::BApplication.
|
||||||
|
|
||||||
|
Drag-and-drop
|
||||||
|
-------------
|
||||||
|
|
||||||
|
Methods
|
||||||
|
-------
|
||||||
|
|
||||||
|
Messaging with the app_server is not done using BMessages because of the
|
||||||
|
overhead required to send them costs time and speed. Instead, ports are
|
||||||
|
utilized indirectly by means of the PortLink class, which simply makes
|
||||||
|
attaching data to a port message easier, but requires very little
|
||||||
|
overhead.
|
||||||
|
|
||||||
|
|
||||||
@@ -0,0 +1,75 @@
|
|||||||
|
Process Management
|
||||||
|
==================
|
||||||
|
|
||||||
|
BApplication execution
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Applications will come in two types: those which communicate with the
|
||||||
|
app_server and take advantage of its services, and those which do not.
|
||||||
|
To access the app_server, an application must be derived from
|
||||||
|
BApplication.
|
||||||
|
|
||||||
|
When a BApplication (referred to hereafter as a BApp) is executed, the
|
||||||
|
app constructor creates its BLooper message port with the name
|
||||||
|
AppLooperPort. This port's id, by means of BLooper, registers its
|
||||||
|
port_id with the app_server so that the two can communicate with each
|
||||||
|
other most easily.
|
||||||
|
|
||||||
|
When the app_server receives notification that an app has been created,
|
||||||
|
the server creates an AppMonitor (with accompanying thread) in its own
|
||||||
|
team to handle messages sent to it and sends a reply with the port_id of
|
||||||
|
the AppMonitor, to which all future messages are sent. These AppMonitor
|
||||||
|
objects are stored in a global BList created for the storage of such
|
||||||
|
things.
|
||||||
|
|
||||||
|
This setup normally requires that there is a single app_server instance running, and all
|
||||||
|
BApplications establish contact with it. There are however several exceptions to this:
|
||||||
|
|
||||||
|
- Multi-user and multi-sessions setups are possible, for example with the use of remote_app_server.
|
||||||
|
In this case, each user session (corresponding to UNIX 'login' sessions) can have its own
|
||||||
|
app_server.
|
||||||
|
- The test_app_server is a test tool that allows to run most of app_server code in its own BWindow,
|
||||||
|
displayed inside the main app_server (mainly for debugging app_server code). In this case, the
|
||||||
|
applications are compiled with specific code to connect specifically with the test_app_server.
|
||||||
|
|
||||||
|
non-BApplication execution
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
Other applications do not communicate with the app_server. These
|
||||||
|
applications have no access to app services and do not generally pass
|
||||||
|
BMessages. This includes, but is not limited to, UNIX apps. The
|
||||||
|
app_server ignores such applications except when asked to kill them.
|
||||||
|
|
||||||
|
While, technically, these are not limited to being non-GUI applications,
|
||||||
|
in practice these applications are command-line-only, for the
|
||||||
|
application would be required to (1) render the app_server unable to
|
||||||
|
access video hardware and (2) reinvent existing graphics code to load
|
||||||
|
and use accelerants and draw onto the video buffer. This is extremely
|
||||||
|
bad style and programming practice, not to mention more work than it is
|
||||||
|
worth.
|
||||||
|
|
||||||
|
Killing/Exiting Applications
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
While the input server handles the Team Monitor window, the app_server
|
||||||
|
actually takes care of shutting down teams, peacefully or not. Exiting
|
||||||
|
an app is done simply by sending a B_QUIT_REQUESTED message to
|
||||||
|
particular app. Killing an app is done via kill_team, but all the messy
|
||||||
|
details are handled by the kernel itself through this call. When the
|
||||||
|
user requests a team die via the Team Monitor, the Input Server sends a
|
||||||
|
message to the app_server to kill the team, attaching the team_id. The
|
||||||
|
app_server responds by happily nuking the respective team and notifies
|
||||||
|
the registrar of its forcible removal from the roster.
|
||||||
|
|
||||||
|
System Shutdown
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Although the server maintains an internal list of running GUI
|
||||||
|
applications, when a request to shut down the system is received by the
|
||||||
|
app_server, it will pass the request on to the registrar, which will, in
|
||||||
|
turn, increment its way through the app roster and request each app
|
||||||
|
quit. When each quit request is sent, a timer is started and after
|
||||||
|
timeout, the registrar will ask the server to kill the particular team
|
||||||
|
and continue iterating through the application list.
|
||||||
|
|
||||||
|
|
||||||
@@ -1,6 +1,50 @@
|
|||||||
Application Server
|
Application Server
|
||||||
============================================
|
============================================
|
||||||
|
|
||||||
|
Purpose
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
The app_server provides services to the Haiku by managing processes,
|
||||||
|
filtering and dispatching input from the Input Server to the appropriate
|
||||||
|
applications, and managing all graphics-related tasks.
|
||||||
|
|
||||||
|
Tasks performed by app_server
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The tasks performed by the app_server are grouped in relation to its purpose.
|
||||||
|
|
||||||
|
- Receives and redirects (dispatches) messages from the input server
|
||||||
|
- Responds to messages from apps
|
||||||
|
- Receives and consolidates requests from BView, BWindow, BBitmap, and others to draw stuff (draw bitmap, etc)
|
||||||
|
- Utilizes ports to communicate with child processes
|
||||||
|
- Handles drag & drop messaging
|
||||||
|
- Manages the system clipboard
|
||||||
|
- Loads and Kills processes
|
||||||
|
- Detects absence of Input Server and restarts when not running
|
||||||
|
- Aids in system shutdown
|
||||||
|
- Dynamically loads accelerant portion of graphics driver
|
||||||
|
- Creates a connection with BBitmaps requiring a child view
|
||||||
|
- Draws the blue desktop screen
|
||||||
|
- Provides workspace support
|
||||||
|
- Provides functionality to the BeAPI for drawing primitives, such as rectangles, ellipses, and beziers
|
||||||
|
- Provides a means for BViews to draw on BBitmaps
|
||||||
|
- Manages window behavior with respect to redraw (move to front, minimize, etc)
|
||||||
|
- Returns a frame buffer to direct-access classes
|
||||||
|
- Caches fonts for screen and printer use
|
||||||
|
- Draws text and provides other font API support for the BeAPI classes
|
||||||
|
|
||||||
|
App server components
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
|
||||||
|
/servers/app_server/graphics
|
||||||
|
/servers/app_server/process_management
|
||||||
|
/servers/app_server/input
|
||||||
|
/servers/app_server/messaging
|
||||||
|
|
||||||
|
- `Multiple Monitor Support Spec <MultiMonitor.htm>`__
|
||||||
|
|
||||||
Class Descriptions
|
Class Descriptions
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
@@ -39,11 +83,3 @@ Font Infrastructure
|
|||||||
/servers/app_server/FontServer
|
/servers/app_server/FontServer
|
||||||
/servers/app_server/FontFamily
|
/servers/app_server/FontFamily
|
||||||
|
|
||||||
Other Documents
|
|
||||||
~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
|
|
||||||
/servers/app_server/asis
|
|
||||||
|
|
||||||
- `Multiple Monitor Support Spec <MultiMonitor.htm>`__
|
|
||||||
|
|||||||
Reference in New Issue
Block a user