1 /** 2 * @file scim_panel_agent.h 3 * @brief Defines scim::PanelAgent and their related types. 4 * 5 * scim::PanelAgent is a class used to write Panel daemons. 6 * It acts like a Socket Server and handles all socket clients 7 * issues. 8 */ 9 10 /* 11 * Smart Common Input Method 12 * 13 * Copyright (c) 2004-2005 James Su <suzhe@tsinghua.org.cn> 14 * 15 * 16 * This library is free software; you can redistribute it and/or 17 * modify it under the terms of the GNU Lesser General Public 18 * License as published by the Free Software Foundation; either 19 * version 2 of the License, or (at your option) any later version. 20 * 21 * This library is distributed in the hope that it will be useful, 22 * but WITHOUT ANY WARRANTY; without even the implied warranty of 23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 24 * GNU Lesser General Public License for more details. 25 * 26 * You should have received a copy of the GNU Lesser General Public 27 * License along with this program; if not, write to the 28 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 29 * Boston, MA 02111-1307 USA 30 * 31 * $Id: scim_panel_agent.h,v 1.2 2005/06/11 14:50:31 suzhe Exp $ 32 */ 33 34 #ifndef __SCIM_PANEL_AGENT_H 35 #define __SCIM_PANEL_AGENT_H 36 37 #include <scim_panel_common.h> 38 39 namespace scim { 40 41 /** 42 * @addtogroup Panel 43 * The accessory classes to help develop Panel daemons and FrontEnds 44 * which need to communicate with Panel daemons. 45 * @{ 46 */ 47 48 typedef Slot0<void> 49 PanelAgentSlotVoid; 50 51 typedef Slot1<void, int> 52 PanelAgentSlotInt; 53 54 typedef Slot1<void, const String &> 55 PanelAgentSlotString; 56 57 typedef Slot1<void, const PanelFactoryInfo &> 58 PanelAgentSlotFactoryInfo; 59 60 typedef Slot1<void, const std::vector <PanelFactoryInfo> &> 61 PanelAgentSlotFactoryInfoVector; 62 63 typedef Slot1<void, const LookupTable &> 64 PanelAgentSlotLookupTable; 65 66 typedef Slot1<void, const Property &> 67 PanelAgentSlotProperty; 68 69 typedef Slot1<void, const PropertyList &> 70 PanelAgentSlotPropertyList; 71 72 typedef Slot2<void, int, int> 73 PanelAgentSlotIntInt; 74 75 typedef Slot2<void, int, const Property &> 76 PanelAgentSlotIntProperty; 77 78 typedef Slot2<void, int, const PropertyList &> 79 PanelAgentSlotIntPropertyList; 80 81 typedef Slot2<void, int, const HelperInfo &> 82 PanelAgentSlotIntHelperInfo; 83 84 typedef Slot2<void, const String &, const AttributeList &> 85 PanelAgentSlotAttributeString; 86 87 /** 88 * @brief The class to implement all socket protocol in Panel. 89 * 90 * This class acts like a stand alone SocketServer. 91 * It has its own dedicated main loop, and will be blocked when run () is called. 92 * So run () must be called within a separated thread, in order to not block 93 * the main loop of the Panel program itself. 94 * 95 * Before calling run (), the panel must hook the callback functions to the 96 * corresponding signals. 97 * 98 * Note that, there are two special signals: lock(void) and unlock(void). These 99 * two signals are used to provide a thread lock to PanelAgent, so that PanelAgent 100 * can run correctly within a multi-threading Panel program. 101 */ 102 class PanelAgent 103 { 104 class PanelAgentImpl; 105 PanelAgentImpl *m_impl; 106 107 PanelAgent (const HelperAgent &); 108 const PanelAgent & operator = (const HelperAgent &); 109 110 public: 111 PanelAgent (); 112 ~PanelAgent (); 113 114 /** 115 * @brief Initialize this PanelAgent. 116 * 117 * @param config The name of the config module to be used by Helpers. 118 * @param display The name of display, on which the Panel should run. 119 * @param resident If this is true then this PanelAgent will keep running 120 * even if there is no more client connected. 121 * 122 * @return true if the PanelAgent is initialized correctly and ready to run. 123 */ 124 bool initialize (const String &config, const String &display, bool resident = false); 125 126 /** 127 * @brief Check if this PanelAgent is initialized correctly and ready to run. 128 * 129 * @return true if this PanelAgent is ready to run. 130 */ 131 bool valid (void) const; 132 133 /** 134 * @brief Run this PanelAgent. 135 * 136 * This method has its own dedicated main loop, 137 * so it should be run in a separated thread. 138 * 139 * @return false if the Panel SocketServer encountered an error when running. 140 * Otherwise, it won't return until the server exits. 141 */ 142 bool run (void); 143 144 /** 145 * @brief Stop this PanelAgent. 146 */ 147 void stop (void); 148 149 public: 150 151 /** 152 * @brief Get the list of all helpers. 153 * 154 * Panel program should provide a menu which contains 155 * all stand alone but not auto start Helpers, so that users can activate 156 * the Helpers by clicking in the menu. 157 * 158 * All auto start Helpers should be started by Panel after running PanelAgent 159 * by calling PanelAgent::start_helper(). 160 * 161 * @param helpers A list contains information of all Helpers. 162 */ 163 int get_helper_list (std::vector <HelperInfo> & helpers) const; 164 165 public: 166 /** 167 * @brief Let the focused IMEngineInstance object move the preedit caret. 168 * 169 * @param position The new preedit caret position. 170 * @return true if the command was sent correctly. 171 */ 172 bool move_preedit_caret (uint32 position); 173 174 /** 175 * @brief Request help information from the focused IMEngineInstance object. 176 * @return true if the command was sent correctly. 177 */ 178 bool request_help (void); 179 180 /** 181 * @brief Request factory menu from the focused FrontEnd. 182 * @return true if the command was sent correctly. 183 */ 184 bool request_factory_menu (void); 185 186 /** 187 * @brief Change the factory used by the focused IMEngineInstance object. 188 * 189 * @param uuid The uuid of the new factory. 190 * @return true if the command was sent correctly. 191 */ 192 bool change_factory (const String &uuid); 193 194 /** 195 * @brief Let the focused IMEngineInstance object 196 * select a candidate in current lookup table. 197 * 198 * @param item The index of the selected candidate. 199 * @return true if the command was sent correctly. 200 */ 201 bool select_candidate (uint32 item); 202 203 /** 204 * @brief Let the focused IMEngineInstance object 205 * flip the LookupTable to previous page. 206 * @return true if the command was sent correctly. 207 */ 208 bool lookup_table_page_up (void); 209 210 /** 211 * @brief Let the focused IMEngineInstance object 212 * flip the LookupTable to next page. 213 * @return true if the command was sent correctly. 214 */ 215 bool lookup_table_page_down (void); 216 217 /** 218 * @brief Let the focused IMEngineInstance object 219 * update the page size of the LookupTable. 220 * 221 * @param size The new page size. 222 * @return true if the command was sent correctly. 223 */ 224 bool update_lookup_table_page_size (uint32 size); 225 226 /** 227 * @brief Trigger a property of the focused IMEngineInstance object. 228 * 229 * @param property The property key to be triggered. 230 * @return true if the command was sent correctly. 231 */ 232 bool trigger_property (const String &property); 233 234 /** 235 * @brief Trigger a property of a Helper object. 236 * 237 * @param client The client id of the Helper object. 238 * @param property The property key to be triggered. 239 * @return true if the command was sent correctly. 240 */ 241 bool trigger_helper_property (int client, 242 const String &property); 243 244 /** 245 * @brief Start a stand alone helper. 246 * 247 * @param uuid The uuid of the Helper object to be started. 248 * @return true if the command was sent correctly. 249 */ 250 bool start_helper (const String &uuid); 251 252 /** 253 * @brief Let all FrontEnds and Helpers reload configuration. 254 * @return true if the command was sent correctly. 255 */ 256 bool reload_config (void); 257 258 /** 259 * @brief Let all FrontEnds, Helpers and this Panel exit. 260 * @return true if the command was sent correctly. 261 */ 262 bool exit (void); 263 264 public: 265 /** 266 * @brief Signal: Reload configuration. 267 * 268 * When a Helper object send a RELOAD_CONFIG event to this Panel, 269 * this signal will be emitted. Panel should reload all configuration here. 270 */ 271 Connection signal_connect_reload_config (PanelAgentSlotVoid *slot); 272 273 /** 274 * @brief Signal: Turn on. 275 * 276 * slot prototype: void turn_on (void); 277 */ 278 Connection signal_connect_turn_on (PanelAgentSlotVoid *slot); 279 280 /** 281 * @brief Signal: Turn off. 282 * 283 * slot prototype: void turn_off (void); 284 */ 285 Connection signal_connect_turn_off (PanelAgentSlotVoid *slot); 286 287 /** 288 * @brief Signal: Update screen. 289 * 290 * slot prototype: void update_screen (int screen); 291 */ 292 Connection signal_connect_update_screen (PanelAgentSlotInt *slot); 293 294 /** 295 * @brief Signal: Update spot location. 296 * 297 * slot prototype: void update_spot_location (int x, int y); 298 */ 299 Connection signal_connect_update_spot_location (PanelAgentSlotIntInt *slot); 300 301 /** 302 * @brief Signal: Update factory information. 303 * 304 * slot prototype: void update_factory_info (const PanelFactoryInfo &info); 305 */ 306 Connection signal_connect_update_factory_info (PanelAgentSlotFactoryInfo *slot); 307 308 /** 309 * @brief Signal: Show help. 310 * 311 * slot prototype: void show_help (const String &help); 312 */ 313 Connection signal_connect_show_help (PanelAgentSlotString *slot); 314 315 /** 316 * @brief Signal: Show factory menu. 317 * 318 * slot prototype: void show_factory_menu (const std::vector <PanelFactoryInfo> &menu); 319 */ 320 Connection signal_connect_show_factory_menu (PanelAgentSlotFactoryInfoVector *slot); 321 322 /** 323 * @brief Signal: Show preedit string. 324 * 325 * slot prototype: void show_preedit_string (void): 326 */ 327 Connection signal_connect_show_preedit_string (PanelAgentSlotVoid *slot); 328 329 /** 330 * @brief Signal: Show aux string. 331 * 332 * slot prototype: void show_aux_string (void): 333 */ 334 Connection signal_connect_show_aux_string (PanelAgentSlotVoid *slot); 335 336 /** 337 * @brief Signal: Show lookup table. 338 * 339 * slot prototype: void show_lookup_table (void): 340 */ 341 Connection signal_connect_show_lookup_table (PanelAgentSlotVoid *slot); 342 343 /** 344 * @brief Signal: Hide preedit string. 345 * 346 * slot prototype: void hide_preedit_string (void); 347 */ 348 Connection signal_connect_hide_preedit_string (PanelAgentSlotVoid *slot); 349 350 /** 351 * @brief Signal: Hide aux string. 352 * 353 * slot prototype: void hide_aux_string (void); 354 */ 355 Connection signal_connect_hide_aux_string (PanelAgentSlotVoid *slot); 356 357 /** 358 * @brief Signal: Hide lookup table. 359 * 360 * slot prototype: void hide_lookup_table (void); 361 */ 362 Connection signal_connect_hide_lookup_table (PanelAgentSlotVoid *slot); 363 364 /** 365 * @brief Signal: Update preedit string. 366 * 367 * slot prototype: void update_preedit_string (const String &str, const AttributeList &attrs); 368 * - str -- The UTF-8 encoded string to be displayed in preedit area. 369 * - attrs -- The attributes of the string. 370 */ 371 Connection signal_connect_update_preedit_string (PanelAgentSlotAttributeString *slot); 372 373 /** 374 * @brief Signal: Update preedit caret. 375 * 376 * slot prototype: void update_preedit_caret (int caret); 377 */ 378 Connection signal_connect_update_preedit_caret (PanelAgentSlotInt *slot); 379 380 /** 381 * @brief Signal: Update aux string. 382 * 383 * slot prototype: void update_aux_string (const String &str, const AttributeList &attrs); 384 * - str -- The UTF-8 encoded string to be displayed in aux area. 385 * - attrs -- The attributes of the string. 386 */ 387 Connection signal_connect_update_aux_string (PanelAgentSlotAttributeString *slot); 388 389 /** 390 * @brief Signal: Update lookup table. 391 * 392 * slot prototype: void update_lookup_table (const LookupTable &table); 393 * - table -- The new LookupTable object. 394 */ 395 Connection signal_connect_update_lookup_table (PanelAgentSlotLookupTable *slot); 396 397 /** 398 * @brief Signal: Register properties. 399 * 400 * Register properties of the focused instance. 401 * 402 * slot prototype: void register_properties (const PropertyList &props); 403 * - props -- The properties to be registered. 404 */ 405 Connection signal_connect_register_properties (PanelAgentSlotPropertyList *slot); 406 407 /** 408 * @brief Signal: Update property. 409 * 410 * Update a property of the focused instance. 411 * 412 * slot prototype: void update_property (const Property &prop); 413 * - prop -- The property to be updated. 414 */ 415 Connection signal_connect_update_property (PanelAgentSlotProperty *slot); 416 417 /** 418 * @brief Signal: Register properties of a helper. 419 * 420 * slot prototype: void register_helper_properties (int id, const PropertyList &props); 421 * - id -- The client id of the helper object. 422 * - props -- The properties to be registered. 423 */ 424 Connection signal_connect_register_helper_properties (PanelAgentSlotIntPropertyList *slot); 425 426 /** 427 * @brief Signal: Update helper property. 428 * 429 * slot prototype: void update_helper_property (int id, const Property &prop); 430 * - id -- The client id of the helper object. 431 * - prop -- The property to be updated. 432 */ 433 Connection signal_connect_update_helper_property (PanelAgentSlotIntProperty *slot); 434 435 /** 436 * @brief Signal: Register a helper object. 437 * 438 * A newly started helper object will send this event to Panel. 439 * 440 * slot prototype: register_helper (int id, const HelperInfo &helper); 441 * - id -- The client id of the helper object. 442 * - helper -- The information of the helper object. 443 */ 444 Connection signal_connect_register_helper (PanelAgentSlotIntHelperInfo *slot); 445 446 /** 447 * @brief Signal: Remove a helper object. 448 * 449 * If a running helper close its connection to Panel, then this signal will be triggered to 450 * tell Panel to remove all data associated to this helper. 451 * 452 * slot prototype: void remove_helper (int id); 453 * - id -- The client id of the helper object to be removed. 454 */ 455 Connection signal_connect_remove_helper (PanelAgentSlotInt *slot); 456 457 /** 458 * @brief Signal: A transaction is started. 459 * 460 * This signal infers that the Panel should disable update before this transaction finishes. 461 * 462 * slot prototype: void signal_connect_transaction_start (void); 463 */ 464 Connection signal_connect_transaction_start (PanelAgentSlotVoid *slot); 465 466 /** 467 * @brief Signal: A transaction is finished. 468 * 469 * This signal will get emitted when a transaction is finished. This implys to re-enable 470 * panel GUI update 471 * 472 * slot prototype: void signal_connect_transaction_end (void); 473 */ 474 Connection signal_connect_transaction_end (PanelAgentSlotVoid *slot); 475 476 /** 477 * @brief Signal: Lock the exclusive lock for this PanelAgent. 478 * 479 * The panel program should provide a thread lock and hook a slot into this signal to lock it. 480 * PanelAgent will use this lock to ensure the data integrity. 481 * 482 * slot prototype: void lock (void); 483 */ 484 Connection signal_connect_lock (PanelAgentSlotVoid *slot); 485 486 /** 487 * @brief Signal: Unlock the exclusive lock for this PanelAgent. 488 * 489 * slot prototype: void unlock (void); 490 */ 491 Connection signal_connect_unlock (PanelAgentSlotVoid *slot); 492 }; 493 494 /** @} */ 495 496 } // namespace scim 497 498 #endif //__SCIM_PANEL_AGENT_H 499 500 /* 501 vi:ts=4:nowrap:ai:expandtab 502 */ 503 504