Add a description (for GUI tooltip) to LXHotkeyAttr.
[lxde/lxhotkey.git] / src / lxhotkey.h
1 /*
2 * Copyright (C) 2016 Andriy Grytsenko <andrej@rep.kiev.ua>
3 *
4 * This file is a part of LXHotkey project.
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 */
20
21 #ifndef _LXKEYS_H_
22 #define _LXKEYS_H_ 1
23
24 #include <libfm/fm.h>
25
26 G_BEGIN_DECLS
27
28 /**
29 * LXHotkeyAttr:
30 * @name: action or option name
31 * @values: (element-type char *): option value
32 * @subopts: (element-type LXHotkeyAttr): (allow-none): list of suboptions
33 * @desc: (allow-none): action or option description
34 * @has_actions: %TRUE if @subopts contains actions, %FALSE if @subopts contains options
35 *
36 * Data descriptor for actions and options. Actions are ativated by keybinding.
37 * Each action may contain arbitrary number of options that alter its execution.
38 *
39 * This data is also used in a result on LXHotkeyPluginInit:get_wm_actions() or
40 * LXHotkeyPluginInit:get_app_options() call. In that case for each option the
41 * @values list should be either %NULL if option accepts any value, or list of
42 * acceptable values for the option ("#" value has a special meaning: integer
43 * value matches it, the same as "%" for percent value). For such purpose it is
44 * advisable to make @name and @values translateable constants because GUI might
45 * represent them in target locale which might be convenient for users.
46 *
47 * The @desc appears in data returned by LXHotkeyPluginInit:get_wm_actions() or
48 * LXHotkeyPluginInit:get_app_options() call, it has human-readable descriptions
49 * for option or action which can be used in GUI tooltip.
50 */
51 typedef struct {
52 gchar *name;
53 GList *values;
54 GList *subopts;
55 gchar *desc;
56 gboolean has_actions;
57 } LXHotkeyAttr;
58
59 /**
60 * LXHotkeyGlobal:
61 * @actions: (element-type LXHotkeyAttr): list of actions
62 * @accel1: a keybinding to activate @actions, in GDK accelerator format
63 * @accel2: optional alternate keybinding to activate @actions
64 * @data1: a pointer for using by WM plugin
65 * @data2: a pointer for using by WM plugin
66 *
67 * Descriptor of a keybinding which isn't a single command line action.
68 * The keybinding string is in format that looks like "<Control>a" or
69 * "<Shift><Alt>F1" or "<Release>z" (note that not each WM supports last one
70 * variant).
71 */
72 typedef struct {
73 GList *actions;
74 gchar *accel1;
75 gchar *accel2;
76 gpointer data1;
77 gpointer data2;
78 } LXHotkeyGlobal;
79
80 /**
81 * LXHotkeyApp:
82 * @exec: a command line to execute
83 * @actions: (element-type LXHotkeyAttr): (allow-none): list of options
84 * @accel1: a keybinding to activate @exec, in GDK accelerator format
85 * @accel2: optional alternate keybinding to activate @exec
86 * @data1: a pointer for using by WM plugin
87 * @data2: a pointer for using by WM plugin
88 *
89 * Descriptor of a keybinding for a single command line action. The command
90 * execution may be altered by some @options. See also #LXHotkeyGlobal.
91 */
92 typedef struct {
93 gchar *exec;
94 GList *options;
95 gchar *accel1;
96 gchar *accel2;
97 gpointer data1;
98 gpointer data2;
99 } LXHotkeyApp;
100
101
102 /* WM support plugins */
103
104 #define FM_MODULE_lxhotkey_VERSION 1 /* version of this API */
105
106 /**
107 * LXHotkeyPluginInit:
108 * @load: callback to (re)load bindings from WM configuration
109 * @save: callback to save bindings to WM configuration
110 * @free: callback to release allocated resources
111 * @get_wm_keys: (allow-none): callback to get global keys by provided mask
112 * @set_wm_key: (allow-none): callback to set a global key by provided data
113 * @get_wm_actions: (allow-none): callback to get global actions list provided by WM
114 * @get_app_keys: (allow-none): callback to get keys bound to commands
115 * @set_app_key: (allow-none): callback to set a key for a command
116 * @get_app_options: (allow-none): callback to get possible actions for commands
117 *
118 * Callbacks @get_wm_keys and @get_app_keys return list which should be freed
119 * by caller (transfer container).
120 * Callbacks @get_wm_actions and @get_app_actions return list that should be
121 * not modified nor freed by caller (transfer none).
122 * Callback @get_wm_keys returns list of keybindings by @mask which is a shell
123 * style pattern for keys.
124 * Callback @set_wm_key changes a keybinding for list of actions provided. If
125 * @data::accel1 is %NULL then all keybindings for @data::actions will be
126 * cleared, otherwise keybindings will be changed accordingly.
127 */
128 typedef struct {
129 /*< public >*/
130 gpointer (*load)(gpointer config, GError **error);
131 gboolean (*save)(gpointer config, GError **error);
132 void (*free)(gpointer config);
133 GList *(*get_wm_keys)(gpointer config, const char *mask, GError **error);
134 gboolean (*set_wm_key)(gpointer config, LXHotkeyGlobal *data, GError **error);
135 GList *(*get_wm_actions)(gpointer config, GError **error);
136 GList *(*get_app_keys)(gpointer config, const char *mask, GError **error);
137 gboolean (*set_app_key)(gpointer config, LXHotkeyApp *data, GError **error);
138 GList *(*get_app_options)(gpointer config, GError **error);
139 /*< private >*/
140 gpointer _reserved1;
141 gpointer _reserved2;
142 gpointer _reserved3;
143 } LXHotkeyPluginInit;
144
145 /**
146 * This descriptor instance should be defined in each plugin code as main
147 * entry point for plugin creation. Primitive plugin example follows:
148 *
149 * #include <lxhotkey/lxhotkey.h>
150 *
151 * gpointer test_load(gpointer config, GError **error)
152 * {
153 * if (config == NULL)
154 * config = g_strdup("");
155 * return config;
156 * }
157 *
158 * gboolean test_save(gpointer config, GError **error)
159 * {
160 * return FALSE;
161 * }
162 *
163 * FM_DEFINE_MODULE(lxhotkey, NoWM)
164 *
165 * LXHotkeyPluginInit fm_module_init_lxhotkey = {
166 * .load = test_load,
167 * .save = test_save,
168 * .free = g_free
169 * }
170 */
171 extern LXHotkeyPluginInit fm_module_init_lxhotkey;
172
173
174 /* GUI plugins */
175
176 #define FM_MODULE_lxhotkey_gui_VERSION 1 /* version of this API */
177
178 /**
179 * LXHotkeyGUIPluginInit:
180 * @run: callback to run GUI
181 * @alert: callback to show an error message
182 *
183 * The @run callback receives name of WM, pointer to callbacks, and pointer to
184 * the config data which is already succesfully loaded and ready to use.
185 */
186 typedef struct {
187 /*< public >*/
188 void (*run)(const gchar *wm, const LXHotkeyPluginInit *cb, gpointer config, GError **error);
189 void (*alert)(GError *error);
190 /*< private >*/
191 gpointer _reserved1;
192 gpointer _reserved2;
193 gpointer _reserved3;
194 } LXHotkeyGUIPluginInit;
195
196 /**
197 * This descriptor instance should be defined in each plugin code as main
198 * entry point for a GUI plugin creation.
199 */
200 extern LXHotkeyGUIPluginInit fm_module_init_lxhotkey_gui;
201
202 G_END_DECLS
203
204 #endif /* _LXKEYS_H_ */