9ea6ececd48e5a578f03847bfcd87b310e6cba75
[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 * @has_actions: %TRUE if @subopts contains actions, %FALSE if @subopts contains options
34 *
35 * Data descriptor for actions and options. Actions are ativated by keybinding.
36 * Each action may contain arbitrary number of options that alter its execution.
37 *
38 * This data is also used in a result on LXHotkeyPluginInit:get_wm_actions() or
39 * LXHotkeyPluginInit:get_app_options() call. In that case for each option the
40 * @values list should be either %NULL if option accepts any value, or list of
41 * acceptable values for the option ("#" value has a special meaning: integer
42 * value matches it, the same as "%" for percent value). For such purpose it is
43 * advisable to make @name and @values translateable constants because GUI might
44 * represent them in target locale which might be convenient for users.
45 */
46 typedef struct {
47 gchar *name;
48 GList *values;
49 GList *subopts;
50 gboolean has_actions;
51 } LXHotkeyAttr;
52
53 /**
54 * LXHotkeyGlobal:
55 * @actions: (element-type LXHotkeyAttr): list of actions
56 * @accel1: a keybinding to activate @actions, in GDK accelerator format
57 * @accel2: optional alternate keybinding to activate @actions
58 * @data1: a pointer for using by WM plugin
59 * @data2: a pointer for using by WM plugin
60 *
61 * Descriptor of a keybinding which isn't a single command line action.
62 * The keybinding string is in format that looks like "<Control>a" or
63 * "<Shift><Alt>F1" or "<Release>z" (note that not each WM supports last one
64 * variant).
65 */
66 typedef struct {
67 GList *actions;
68 gchar *accel1;
69 gchar *accel2;
70 gpointer data1;
71 gpointer data2;
72 } LXHotkeyGlobal;
73
74 /**
75 * LXHotkeyApp:
76 * @exec: a command line to execute
77 * @actions: (element-type LXHotkeyAttr): (allow-none): list of options
78 * @accel1: a keybinding to activate @exec, in GDK accelerator format
79 * @accel2: optional alternate keybinding to activate @exec
80 * @data1: a pointer for using by WM plugin
81 * @data2: a pointer for using by WM plugin
82 *
83 * Descriptor of a keybinding for a single command line action. The command
84 * execution may be altered by some @options. See also #LXHotkeyGlobal.
85 */
86 typedef struct {
87 gchar *exec;
88 GList *options;
89 gchar *accel1;
90 gchar *accel2;
91 gpointer data1;
92 gpointer data2;
93 } LXHotkeyApp;
94
95
96 /* WM support plugins */
97
98 #define FM_MODULE_lxhotkey_VERSION 1 /* version of this API */
99
100 /**
101 * LXHotkeyPluginInit:
102 * @load: callback to (re)load bindings from WM configuration
103 * @save: callback to save bindings to WM configuration
104 * @free: callback to release allocated resources
105 * @get_wm_keys: (allow-none): callback to get global keys by provided mask
106 * @set_wm_key: (allow-none): callback to set a global key by provided data
107 * @get_wm_actions: (allow-none): callback to get global actions list provided by WM
108 * @get_app_keys: (allow-none): callback to get keys bound to commands
109 * @set_app_key: (allow-none): callback to set a key for a command
110 * @get_app_options: (allow-none): callback to get possible actions for commands
111 *
112 * Callbacks @get_wm_keys and @get_app_keys return list which should be freed
113 * by caller (transfer container).
114 * Callbacks @get_wm_actions and @get_app_actions return list that should be
115 * not modified nor freed by caller (transfer none).
116 * Callback @get_wm_keys returns list of keybindings by @mask which is a shell
117 * style pattern for keys.
118 * Callback @set_wm_key changes a keybinding for list of actions provided. If
119 * @data::accel1 is %NULL then all keybindings for @data::actions will be
120 * cleared, otherwise keybindings will be changed accordingly.
121 */
122 typedef struct {
123 /*< public >*/
124 gpointer (*load)(gpointer config, GError **error);
125 gboolean (*save)(gpointer config, GError **error);
126 void (*free)(gpointer config);
127 GList *(*get_wm_keys)(gpointer config, const char *mask, GError **error);
128 gboolean (*set_wm_key)(gpointer config, LXHotkeyGlobal *data, GError **error);
129 GList *(*get_wm_actions)(gpointer config, GError **error);
130 GList *(*get_app_keys)(gpointer config, const char *mask, GError **error);
131 gboolean (*set_app_key)(gpointer config, LXHotkeyApp *data, GError **error);
132 GList *(*get_app_options)(gpointer config, GError **error);
133 /*< private >*/
134 gpointer _reserved1;
135 gpointer _reserved2;
136 gpointer _reserved3;
137 } LXHotkeyPluginInit;
138
139 /**
140 * This descriptor instance should be defined in each plugin code as main
141 * entry point for plugin creation. Primitive plugin example follows:
142 *
143 * #include <lxhotkey/lxhotkey.h>
144 *
145 * gpointer test_load(gpointer config, GError **error)
146 * {
147 * if (config == NULL)
148 * config = g_strdup("");
149 * return config;
150 * }
151 *
152 * gboolean test_save(gpointer config, GError **error)
153 * {
154 * return FALSE;
155 * }
156 *
157 * FM_DEFINE_MODULE(lxhotkey, NoWM)
158 *
159 * LXHotkeyPluginInit fm_module_init_lxhotkey = {
160 * .load = test_load,
161 * .save = test_save,
162 * .free = g_free
163 * }
164 */
165 extern LXHotkeyPluginInit fm_module_init_lxhotkey;
166
167
168 /* GUI plugins */
169
170 #define FM_MODULE_lxhotkey_gui_VERSION 1 /* version of this API */
171
172 /**
173 * LXHotkeyGUIPluginInit:
174 * @run: callback to run GUI
175 * @alert: callback to show an error message
176 *
177 * The @run callback receives name of WM, pointer to callbacks, and pointer to
178 * the config data which is already succesfully loaded and ready to use.
179 */
180 typedef struct {
181 /*< public >*/
182 void (*run)(const gchar *wm, const LXHotkeyPluginInit *cb, gpointer config, GError **error);
183 void (*alert)(GError *error);
184 /*< private >*/
185 gpointer _reserved1;
186 gpointer _reserved2;
187 gpointer _reserved3;
188 } LXHotkeyGUIPluginInit;
189
190 /**
191 * This descriptor instance should be defined in each plugin code as main
192 * entry point for a GUI plugin creation.
193 */
194 extern LXHotkeyGUIPluginInit fm_module_init_lxhotkey_gui;
195
196 G_END_DECLS
197
198 #endif /* _LXKEYS_H_ */