protocol/tizen/text.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <protocol name="text">
   3
   4   <copyright>
   5     Copyright © 2012, 2013 Intel Corporation
   6
   7     Permission to use, copy, modify, distribute, and sell this
   8     software and its documentation for any purpose is hereby granted
   9     without fee, provided that the above copyright notice appear in
  10     all copies and that both that copyright notice and this permission
  11     notice appear in supporting documentation, and that the name of
  12     the copyright holders not be used in advertising or publicity
  13     pertaining to distribution of the software without specific,
  14     written prior permission.  The copyright holders make no
  15     representations about the suitability of this software for any
  16     purpose.  It is provided "as is" without express or implied
  17     warranty.
  18
  19     THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
  20     SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  21     FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
  22     SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  23     WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
  24     AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  25     ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  26     THIS SOFTWARE.
  27   </copyright>
  28
  29   <interface name="wl_text_input" version="1">
  30     <description summary="text input">
  31       An object used for text input. Adds support for text input and input
  32       methods to applications. A text_input object is created from a
  33       wl_text_input_manager and corresponds typically to a text entry in an
  34       application.
  35
  36       Requests are used to activate/deactivate the text_input object and set
  37       state information like surrounding and selected text or the content type.
  38       The information about entered text is sent to the text_input object via
  39       the pre-edit and commit events. Using this interface removes the need
  40       for applications to directly process hardware key events and compose text
  41       out of them.
  42
  43       Text is generally UTF-8 encoded, indices and lengths are in bytes.
  44
  45       Serials are used to synchronize the state between the text input and
  46       an input method. New serials are sent by the text input in the
  47       commit_state request and are used by the input method to indicate
  48       the known text input state in events like preedit_string, commit_string,
  49       and keysym. The text input can then ignore events from the input method
  50       which are based on an outdated state (for example after a reset).
  51     </description>
  52     <request name="destroy" type="destructor"/>
  53     <request name="activate">
  54       <description summary="request activation">
  55         Requests the text_input object to be activated (typically when the
  56         text entry gets focus).
  57         The seat argument is a wl_seat which maintains the focus for this
  58         activation. The surface argument is a wl_surface assigned to the
  59         text_input object and tracked for focus lost. The enter event
  60         is emitted on successful activation.
  61       </description>
  62       <arg name="seat" type="object" interface="wl_seat"/>
  63       <arg name="surface" type="object" interface="wl_surface"/>
  64     </request>
  65     <request name="deactivate">
  66       <description summary="request deactivation">
  67         Requests the text_input object to be deactivated (typically when the
  68         text entry lost focus). The seat argument is a wl_seat which was used
  69         for activation.
  70       </description>
  71       <arg name="seat" type="object" interface="wl_seat"/>
  72     </request>
  73     <request name="show_input_panel">
  74       <description summary="show input panels">
  75         Requests input panels (virtual keyboard) to show.
  76       </description>
  77     </request>
  78     <request name="hide_input_panel">
  79       <description summary="hide input panels">
  80         Requests input panels (virtual keyboard) to hide.
  81       </description>
  82     </request>
  83     <request name="reset">
  84       <description summary="reset">
  85         Should be called by an editor widget when the input state should be
  86         reset, for example after the text was changed outside of the normal
  87         input method flow.
  88       </description>
  89     </request>
  90     <enum name="content_hint">
  91       <description summary="content hint">
  92         Content hint is a bitmask to allow to modify the behavior of the text
  93         input.
  94       </description>
  95       <entry name="none" value="0x0" summary="no special behaviour"/>
  96       <entry name="default" value="0x7" summary="auto completion, correction and capitalization"/>
  97       <entry name="password" value="0xc0" summary="hidden and sensitive text"/>
  98       <entry name="auto_completion" value="0x1" summary="suggest word completions"/>
  99       <entry name="auto_correction" value="0x2" summary="suggest word corrections"/>
 100       <entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/>
 101       <entry name="lowercase" value="0x8" summary="prefer lowercase letters"/>
 102       <entry name="uppercase" value="0x10" summary="prefer uppercase letters"/>
 103       <entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/>
 104       <entry name="hidden_text" value="0x40" summary="characters should be hidden"/>
 105       <entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
 106       <entry name="latin" value="0x100" summary="just latin characters should be entered"/>
 107       <entry name="multiline" value="0x200" summary="the text input is multiline"/>
 108       <entry name="word_capitalization" value="0x400" summary="switch to uppercase letters at the start of a word"/>
 109       <entry name="autofill_credit_card_expiration_date" value="0x10000" summary="autofilled with credit card expiration date"/>
 110       <entry name="autofill_credit_card_expiration_day" value="0x20000" summary="autofilled with credit card expiration day"/>
 111       <entry name="autofill_credit_card_expiration_month" value="0x30000" summary="autofilled with credit card expiration month"/>
 112       <entry name="autofill_credit_card_expiration_year" value="0x40000" summary="autofilled with credit card expiration year"/>
 113       <entry name="autofill_credit_card_number" value="0x50000" summary="autofilled with credit card number"/>
 114       <entry name="autofill_credit_card_security_code" value="0x60000" summary="autofilled with credit card security code"/>
 115       <entry name="autofill_email_address" value="0x70000" summary="autofilled with email address"/>
 116       <entry name="autofill_phone" value="0x80000" summary="autofilled with phone number"/>
 117       <entry name="autofill_postal_address" value="0x90000" summary="autofilled with postal address"/>
 118       <entry name="autofill_postal_code" value="0xA0000" summary="autofilled with postal code"/>
 119       <entry name="autofill_id" value="0xB0000" summary="autofilled with id"/>
 120       <entry name="autofill_name" value="0xC0000" summary="autofilled with name"/>
 121     </enum>
 122     <enum name="content_purpose">
 123       <description summary="content purpose">
 124         The content purpose allows to specify the primary purpose of a text
 125         input.
 126
 127         This allows an input method to show special purpose input panels with
 128         extra characters or to disallow some characters.
 129       </description>
 130       <entry name="normal" value="0" summary="default input, allowing all characters"/>
 131       <entry name="alpha" value="1" summary="allow only alphabetic characters"/>
 132       <entry name="digits" value="2" summary="allow only digits"/>
 133       <entry name="number" value="3" summary="input a number (including decimal separator and sign)"/>
 134       <entry name="phone" value="4" summary="input a phone number"/>
 135       <entry name="url" value="5" summary="input an URL"/>
 136       <entry name="email" value="6" summary="input an email address"/>
 137       <entry name="name" value="7" summary="input a name of a person"/>
 138       <entry name="password" value="8" summary="input a password (combine with password or sensitive_data hint)"/>
 139       <entry name="date" value="9" summary="input a date"/>
 140       <entry name="time" value="10" summary="input a time"/>
 141       <entry name="datetime" value="11" summary="input a date and time"/>
 142       <entry name="terminal" value="12" summary="input for a terminal"/>
 143       <entry name="ip" value="13" summary="input for a IP (number and a-f for Ipv6)"/>
 144       <entry name="emoticon" value="14" summary="input for an emoticon"/>
 145       <entry name="digits_signed" value="15" summary="allow digits and negative sign"/>
 146       <entry name="digits_decimal" value="16" summary="allow digits and decimal point"/>
 147       <entry name="digits_signeddecimal" value="17" summary="allow digits, negative sign and decimal point"/>
 148       <entry name="password_digits" value="18" summary="input a password with only digits"/>
 149       <entry name="filename" value="19" summary="default input for the name of a file (symbols such as '/' should be disabled)"/>
 150       <entry name="hex" value="20" summary="input for a hexadecimal"/>
 151       <entry name="voice" value="21" summary="input for a voice"/>
 152     </enum>
 153     <request name="set_content_type">
 154       <description summary="set content purpose and hint">
 155         Set the content purpose and content hint. While the purpose is the
 156         basic purpose of an input field, the hint flags allow to modify some
 157         of the behavior.
 158
 159         When no content type is explicitly set, a normal content purpose with
 160         default hints (auto completion, auto correction, auto capitalization)
 161         should be assumed.
 162       </description>
 163       <arg name="hint" type="uint"/>
 164       <arg name="purpose" type="uint"/>
 165     </request>
 166     <request name="set_cursor_rectangle">
 167       <arg name="x" type="int"/>
 168       <arg name="y" type="int"/>
 169       <arg name="width" type="int"/>
 170       <arg name="height" type="int"/>
 171     </request>
 172     <request name="set_preferred_language">
 173       <description summary="set preferred language">
 174         Set a specific language. This allows for example a virtual keyboard to
 175         show a language specific layout. The "language" argument is an RFC-3066
 176         format language tag.
 177
 178         It could be used for example in a word processor to indicate language of
 179         currently edited document or in an instant message application which tracks
 180         languages of contacts.
 181       </description>
 182       <arg name="language" type="string"/>
 183     </request>
 184     <request name="commit_state">
 185       <arg name="serial" type="uint" summary="used to identify the known state"/>
 186     </request>
 187     <request name="invoke_action">
 188       <arg name="button" type="uint"/>
 189       <arg name="index" type="uint"/>
 190     </request>
 191     <enum name="return_key_type">
 192       <description summary="return key type">
 193         The return key type allows to specify the return key on the input panel.
 194       </description>
 195       <entry name="default" value="0" summary="default"/>
 196       <entry name="done" value="1" summary="done"/>
 197       <entry name="go" value="2" summary="go"/>
 198       <entry name="join" value="3" summary="join"/>
 199       <entry name="login" value="4" summary="login"/>
 200       <entry name="next" value="5" summary="next"/>
 201       <entry name="search" value="6" summary="search"/>
 202       <entry name="send" value="7" summary="send"/>
 203     </enum>
 204     <request name="set_return_key_type">
 205       <description summary="set return key type">
 206         Set the return key type.
 207       </description>
 208       <arg name="return_key_type" type="uint"/>
 209     </request>
 210     <request name="set_return_key_disabled">
 211       <description summary="set return key to be disabled">
 212         Set the return key on the input panel to be disabled.
 213       </description>
 214       <arg name="return_key_disabled" type="uint"/>
 215     </request>
 216     <request name="set_input_panel_data">
 217       <description summary="set input panel data">
 218         Set the input panel-specific data to deliver to the input panel.
 219       </description>
 220       <arg name="input_panel_data" type="string"/>
 221       <arg name="input_panel_length" type="uint"/>
 222     </request>
 223     <request name="bidi_direction">
 224       <arg name="direction" type="uint"/>
 225     </request>
 226     <request name="set_cursor_position">
 227       <description summary="set the cursor index">
 228         Set the cursor position to the input panel.
 229       </description>
 230       <arg name="cursor_position" type="uint"/>
 231     </request>
 232     <request name="process_input_device_event">
 233       <description summary="request to process unconventional input device event">
 234         Deliver unconventional input device events that need to be processed by input panel
 235       </description>
 236       <arg name="event_type" type="uint"/>
 237       <arg name="event_data" type="string"/>
 238       <arg name="event_length" type="uint"/>
 239     </request>
 240     <request name="filter_key_event">
 241       <description summary="input panel data">
 242         Filter key event by input method
 243       </description>
 244       <arg name="serial" type="uint"/>
 245       <arg name="time" type="uint"/>
 246       <arg name="keyname" type="string"/>
 247       <arg name="state" type="uint"/>
 248       <arg name="modifiers" type="uint"/>
 249       <arg name="dev_name" type="string"/>
 250       <arg name="dev_class" type="uint"/>
 251       <arg name="dev_subclass" type="uint"/>
 252     </request>
 253     <request name="get_hide_permission">
 254       <description summary="get permission to hide input panel">
 255         Get permission to hide input panel.
 256       </description>
 257     </request>
 258     <enum name="capital_mode">
 259       <description summary="capital mode">
 260         This allows to specify capital mode on the input panel.
 261       </description>
 262       <entry name="uppercase" value="0" summary="uppercase"/>
 263       <entry name="lowercase" value="1" summary="lowercase"/>
 264     </enum>
 265     <request name="set_capital_mode">
 266       <arg name="mode" type="uint"/>
 267     </request>
 268     <request name="prediction_hint">
 269       <description summary="set the prediction hint">
 270         Set the prediction hint string to deliver to the input panel.
 271       </description>
 272       <arg name="text" type="string"/>
 273     </request>
 274     <request name="set_mime_type">
 275       <description summary="set the mime type">
 276         Sets the mime type to deliver to the input panel.
 277       </description>
 278       <arg name="type" type="string"/>
 279     </request>
 280     <request name="set_input_panel_position">
 281       <description summary="set the input panel position">
 282         Set the input panel position.
 283       </description>
 284       <arg name="x" type="uint"/>
 285       <arg name="y" type="uint"/>
 286     </request>
 287     <request name="finalize_content">
 288       <description summary="finalize its content">
 289         Finalized its content right before losing the focus.
 290       </description>
 291       <arg name="text" type="string"/>
 292       <arg name="cursor_position" type="uint"/>
 293     </request>
 294     <request name="prediction_hint_data">
 295       <description summary="set the prediction hint data">
 296         Set the prediction hint data.
 297       </description>
 298       <arg name="key" type="string"/>
 299       <arg name="value" type="string"/>
 300     </request>
 301     <event name="enter">
 302       <description summary="enter event">
 303         Notify the text_input object when it received focus. Typically in
 304         response to an activate request.
 305       </description>
 306       <arg name="surface" type="object" interface="wl_surface"/>
 307     </event>
 308     <event name="leave">
 309       <description summary="leave event">
 310         Notify the text_input object when it lost focus. Either in response
 311         to a deactivate request or when the assigned surface lost focus or was
 312         destroyed.
 313       </description>
 314     </event>
 315     <event name="modifiers_map">
 316       <description summary="modifiers map">
 317         Transfer an array of 0-terminated modifiers names. The position in
 318         the array is the index of the modifier as used in the modifiers
 319         bitmask in the keysym event.
 320       </description>
 321       <arg name="map" type="array"/>
 322     </event>
 323     <enum name="input_panel_state">
 324       <entry name="hide" value="0" summary="Notification prior to the dismissal of the input panel"/>
 325       <entry name="show" value="1" summary="Notification after the display of the input panel"/>
 326     </enum>
 327     <event name="input_panel_state">
 328       <description summary="state of the input panel">
 329         Notify when the visibility state of the input panel changed.
 330       </description>
 331       <arg name="state" type="uint"/>
 332     </event>
 333     <event name="preedit_string">
 334       <description summary="pre-edit">
 335         Notify when a new composing text (pre-edit) should be set around the
 336         current cursor position. Any previously set composing text should
 337         be removed.
 338
 339         The commit text can be used to replace the preedit text on reset
 340         (for example on unfocus).
 341
 342         The text input should also handle all preedit_style and preedit_cursor
 343         events occurring directly before preedit_string.
 344       </description>
 345       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 346       <arg name="text" type="string"/>
 347       <arg name="commit" type="string"/>
 348     </event>
 349     <enum name="preedit_style">
 350       <entry name="default" value="0" summary="default style for composing text"/>
 351       <entry name="none" value="1" summary="style should be the same as in non-composing text"/>
 352       <entry name="active" value="2"/>
 353       <entry name="inactive" value="3"/>
 354       <entry name="highlight" value="4"/>
 355       <entry name="underline" value="5"/>
 356       <entry name="selection" value="6"/>
 357       <entry name="incorrect" value="7"/>
 358     </enum>
 359     <event name="preedit_styling">
 360       <description summary="pre-edit styling">
 361         Set styling information on composing text. The style is applied for
 362         length bytes from index relative to the beginning of the composing
 363         text (as byte offset). Multiple styles can be applied to a composing
 364         text by sending multiple preedit_styling events.
 365
 366         This event is handled as part of a following preedit_string event.
 367       </description>
 368       <arg name="index" type="uint"/>
 369       <arg name="length" type="uint"/>
 370       <arg name="style" type="uint"/>
 371     </event>
 372     <event name="preedit_cursor">
 373       <description summary="pre-edit cursor">
 374         Set the cursor position inside the composing text (as byte
 375         offset) relative to the start of the composing text. When index is a
 376         negative number no cursor is shown.
 377
 378         This event is handled as part of a following preedit_string event.
 379       </description>
 380       <arg name="index" type="int"/>
 381     </event>
 382     <event name="commit_string">
 383       <description summary="commit">
 384         Notify when text should be inserted into the editor widget. The text to
 385         commit could be either just a single character after a key press or the
 386         result of some composing (pre-edit). It could be also an empty text
 387         when some text should be removed (see delete_surrounding_text) or when
 388         the input cursor should be moved (see cursor_position).
 389
 390         Any previously set composing text should be removed.
 391       </description>
 392       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 393       <arg name="text" type="string"/>
 394     </event>
 395     <event name="cursor_position">
 396       <description summary="set cursor to new position">
 397         Notify when the cursor or anchor position should be modified.
 398
 399         This event should be handled as part of a following commit_string
 400         event.
 401       </description>
 402       <arg name="index" type="int"/>
 403       <arg name="anchor" type="int"/>
 404     </event>
 405     <event name="delete_surrounding_text">
 406       <description summary="delete surrounding text">
 407         Notify when the text around the current cursor position should be
 408         deleted.
 409
 410         Index is relative to the current cursor (in bytes).
 411         Length is the length of deleted text (in bytes).
 412
 413         This event should be handled as part of a following commit_string
 414         event.
 415       </description>
 416       <arg name="index" type="int"/>
 417       <arg name="length" type="uint"/>
 418     </event>
 419     <event name="keysym">
 420       <description summary="keysym">
 421         Notify when a key event was sent. Key events should not be used
 422         for normal text input operations, which should be done with
 423         commit_string, delete_surrounding_text, etc. The key event follows
 424         the wl_keyboard key event convention. Sym is a XKB keysym, state a
 425         wl_keyboard key_state. Modifiers are a mask for effective modifiers
 426         (where the modifier indices are set by the modifiers_map event)
 427       </description>
 428       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 429       <arg name="time" type="uint"/>
 430       <arg name="sym" type="uint"/>
 431       <arg name="state" type="uint"/>
 432       <arg name="modifiers" type="uint"/>
 433     </event>
 434     <event name="language">
 435       <description summary="language">
 436         Set the language of the input text. The "language" argument is an RFC-3066
 437         format language tag.
 438       </description>
 439       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 440       <arg name="language" type="string"/>
 441     </event>
 442     <enum name="text_direction">
 443       <entry name="auto" value="0" summary="automatic text direction based on text and language"/>
 444       <entry name="ltr" value="1" summary="left-to-right"/>
 445       <entry name="rtl" value="2" summary="right-to-left"/>
 446     </enum>
 447     <event name="text_direction">
 448       <description summary="text direction">
 449         Set the text direction of input text.
 450
 451         It is mainly needed for showing input cursor on correct side of the
 452         editor when there is no input yet done and making sure neutral
 453         direction text is laid out properly.
 454       </description>
 455       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 456       <arg name="direction" type="uint"/>
 457     </event>
 458     <event name="selection_region">
 459       <description summary="selection region">
 460         Notify when the input panels ask to select the characters
 461         from the start cursor position to the end cursor position.
 462       </description>
 463       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 464       <arg name="start" type="int"/>
 465       <arg name="end" type="int"/>
 466     </event>
 467     <event name="private_command">
 468       <description summary="private command">
 469         Notify when the input panels ask to send private command
 470       </description>
 471       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 472       <arg name="command" type="string"/>
 473     </event>
 474     <event name="input_panel_geometry">
 475       <description summary="geometry of the input panel">
 476         Notify when the geometry of the input panel changed.
 477       </description>
 478       <arg name="x" type="uint"/>
 479       <arg name="y" type="uint"/>
 480       <arg name="width" type="uint"/>
 481       <arg name="height" type="uint"/>
 482     </event>
 483     <event name="input_panel_data">
 484       <description summary="input panel data">
 485         Notify when the input panels ask to send input panel data
 486       </description>
 487       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 488       <arg name="input_panel_data" type="string"/>
 489       <arg name="input_panel_data_length" type="uint"/>
 490     </event>
 491     <event name="get_selection_text">
 492       <arg name="fd" type="fd"/>
 493     </event>
 494     <event name="get_surrounding_text">
 495       <arg name="maxlen_before" type="uint"/>
 496       <arg name="maxlen_after" type="uint"/>
 497       <arg name="fd" type="fd"/>
 498     </event>
 499     <event name="filter_key_event_done">
 500       <arg name="serial" type="uint"/>
 501       <arg name="state" type="uint"/>
 502     </event>
 503     <event name="hide_permission">
 504       <description summary="permission to hide input panel">
 505         Notify whether input panel should be hidden or not.
 506       </description>
 507       <arg name="response" type="uint"/>
 508     </event>
 509     <event name="recapture_string">
 510       <description summary="recapture">
 511         Notify when the existed text should be deleted and a new composing text (pre-edit) or commit string
 512         should be set around the current cursor position.
 513       </description>
 514       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 515       <arg name="index" type="int"/>
 516       <arg name="length" type="uint"/>
 517       <arg name="preedit" type="string"/>
 518       <arg name="preedit_commit" type="string"/>
 519       <arg name="commit" type="string"/>
 520     </event>
 521     <event name="input_panel_event">
 522       <description summary="input panel event">
 523         Notify when the input panel event is changed
 524       </description>
 525       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 526       <arg name="event_type" type="uint"/>
 527       <arg name="value" type="uint"/>
 528     </event>
 529     <event name="commit_content">
 530       <description summary="commit content">
 531         Notify when the input panel wants to commit a content
 532       </description>
 533       <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
 534       <arg name="content" type="string"/>
 535       <arg name="description" type="string"/>
 536       <arg name="mime_types" type="string"/>
 537     </event>
 538   </interface>
 539
 540   <interface name="wl_text_input_manager" version="1">
 541     <description summary="text input manager">
 542       A factory for text_input objects. This object is a global singleton.
 543     </description>
 544     <request name="create_text_input">
 545       <description summary="create text input">
 546         Creates a new text_input object.
 547       </description>
 548       <arg name="id" type="new_id" interface="wl_text_input"/>
 549     </request>
 550   </interface>
 551 </protocol>