.\" Copyright (c) 2012-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt AG_KEYBOARD 3 .Os Agar 1.7 .Sh NAME .Nm AG_Keyboard .Nd agar direct keyboard interface .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION The .Nm interface provides a direct interface to keyboard status. This manual page also documents a few utility routines for dealing with Agar keyboard symbols. The .Nm object itself is registered and accessed through the .Xr AG_Driver 3 interface. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Xr AG_InputDevice 3 -> .Nm . .Sh WIDGET INTERFACE .nr nS 1 .Ft "const char *" .Fn AG_LookupKeyName "AG_KeySym sym" .Pp .Ft "char *" .Fn AG_LookupKeyMod "AG_KeyMod mod" .Pp .Ft "AG_KeySym" .Fn AG_LookupKeySym "const char *name" .Pp .Ft "int *" .Fn AG_GetKeyState "AG_Widget *widget" .Pp .Ft "int" .Fn AG_GetKeyCount "AG_Widget *widget" .Pp .Ft "void" .Fn AG_SetKeyState "AG_Widget *widget" "int *keyState" .Pp .Ft "Uint" .Fn AG_GetModState "AG_Widget *widget" .Pp .Ft "void" .Fn AG_SetModState "AG_Widget *widget" "Uint modState" .Pp .Ft "int" .Fn AG_CompareKeyMods "Uint modState" "const char *flags" .Pp .nr nS 0 The .Fn AG_LookupKeyName function returns a pointer to a statically-allocated, user-readable string describing the given .Xr AG_KeySym 3 (or NULL if the argument is out of range). .Pp The .Fn AG_LookupKeyMod function returns a dynamically-allocated, user-readable string describing the given .Xr AG_KeyMod 3 . .Pp .Fn AG_LookupKeySym returns a keysym value for the specified name (or .Dv AG_KEY_NONE if no match was found). .Pp The .Fn AG_GetKeyState function returns a pointer to an array of integers which represent the current keyboard status. The array has up to .Dv AG_KEY_LAST entries (see .Xr AG_KeySym 3 ) . .Fn AG_GetKeyCount returns the number of entries in the keyboard status array. .Pp The .Fn AG_SetKeyState routine overwrites the keyboard status array with the contents of .Fa keyState (which should have .Dv AG_KEY_LAST entries). .Pp .Fn AG_GetModState returns the current keyboard modifier status (see .Xr AG_KeyMod 3 ) . .Fn AG_SetModState overwrites the current modifier status with the value of .Fa modState . .Pp The .Fn AG_CompareKeyMods function compares a modifier status against a string of flags, returning 1 if any of the modifiers described by the string are active, or 0 otherwise. No distinction is made between left and right-sided modifiers. The string may contain "C" for CTRL, "A" for ALT, "S" for SHIFT, and "M" for META. .Sh INTERNAL DRIVER INTERFACE .nr nS 1 .Ft "AG_Keyboard *" .Fn AG_KeyboardNew "AG_Driver *drv" "const char *descr" .Pp .Ft "void" .Fn AG_KeyboardUpdate "AG_Keyboard *kbd" "AG_KeyboardAction action" "AG_KeySym sym" .Pp .Ft "int" .Fn AG_ProcessKey "AG_Keyboard *kbd" "AG_Window *win" "AG_KeyboardAction action" "AG_KeySym sym" "Uint32 unicode" .Pp .nr nS 0 The .Fn AG_KeyboardNew function registers a new keyboard device under the specified .Xr AG_Driver 3 . .Pp When a keyboard event is received by the driver, it should call .Fn AG_KeyboardUpdate to update Agar's internal keyboard status as soon as the event is received. Typically, .Fn AG_KeyboardUpdate is called by the .Fn GetNextEvent routine of the driver (see .Xr AG_GetNextEvent 3 ) . .Pp The .Fn AG_ProcessKey function is called to perform final processing of key press and key release events (sending .Sq key-up and .Sq key-down events to the appropriate Agar widgets). Typically, .Fn AG_ProcessKey is called from the .Fn ProcessEvent routine of the driver (see .Xr AG_ProcessEvent 3 ) . The .Va agDrivers must be locked. .Pp .Fn AG_KeyboardUpdate and .Fn AG_ProcessKey accept the same arguments. .Fa action should be .Dv AG_KEY_PRESSED or .Dv AG_KEY_RELEASED . The .Fa sym argument is the Agar virtual key (see .Xr AG_KeySym 3 ) , and .Fa unicode is the Unicode character value. Either (but not both) arguments may be undefined. .Fa sym may be set to .Dv AG_KEY_NONE if there is no corresponding Agar virtual key, and .Fa unicode may be set to 0 if there is no corresponding Unicode character (as should be the case for function keys). .Sh SEE ALSO .Xr AG_Intro 3 , .Xr AG_KeyMod 3 , .Xr AG_KeySym 3 , .Xr AG_Widget 3 , .Xr AG_Window 3 .Sh HISTORY The .Nm interface first appeared in Agar 1.4.0 and the widget interface was first documented in Agar 1.5.0.