← Back to branch summary

~brandontschaefer/mir/first-round-deprecation

« back to all changes in this revision

Viewing changes to include/client/mir_toolkit/mir_input_device.h

  • Committer: Brandon Schaefer
  • Date: 2016-12-13 17:59:30 UTC
  • mfrom: (3787.1.93 development-branch)
  • Revision ID: brandon.schaefer@canonical.com-20161213175930-j9o7qn0b11n3kzlm
* Merge trunk, fix conflicts

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/client/mir_toolkit/mir_input_device.h
49
49
    mir_pointer_acceleration_adaptive = 2
50
50
} MirPointerAcceleration;
51
51
 
 
52
/**
 
53
 * MirTouchpadClickMode configures how the touchpad itself should generate
 
54
 * pointer button events. The available click modes may be active
 
55
 * simultaneously.
 
56
 * - mir_touchpad_click_mode_none: no active click mode
 
57
 * - mir_touchpad_click_mode_area_to_click: simulate pointer buttons using
 
58
 *   click areas on the touchpad
 
59
 * - mir_touchpad_click_mode_finger_count: simulate pointer buttons using the
 
60
 *   number of fingers down
 
61
 */
52
62
typedef enum MirTouchpadClickMode
53
63
{
54
64
    mir_touchpad_click_mode_none          = 0,
57
67
} MirTouchpadClickMode;
58
68
typedef unsigned int MirTouchpadClickModes;
59
69
 
 
70
/**
 
71
 * MirTouchpadScrollMode configures how the touchpad should generate scroll
 
72
 * events.
 
73
 * - mir_touchpad_scroll_mode_none: no scroll
 
74
 * - mir_touchpad_scroll_mode_two_finger_scroll: two finger movement generates
 
75
 *   generates vertical and horizontal scroll events
 
76
 * - mir_touchpad_scroll_mode_edge_scroll: touch movement at the edge of the
 
77
 *   touchpad genertes scroll events
 
78
 * - mir_touchpad_scroll_mode_button_down_scroll: movement on the touchpad
 
79
 *   generates scroll events when a button is held down simultaneously
 
80
 */
60
81
typedef enum MirTouchpadScrollMode
61
82
{
62
83
    mir_touchpad_scroll_mode_none               = 0,
194
215
 */
195
216
char const* mir_input_device_get_unique_id(MirInputDevice const* device);
196
217
 
 
218
/**
 
219
 * Retrieve a structure containing the pointer related configuration options
 
220
 * of the input device.
 
221
 *
 
222
 * If the input device does not control the mouse cursor, there will be no
 
223
 * configuration options, and the function will return a null pointer.
 
224
 *
 
225
 * \param [in] device   The input device
 
226
 *
 
227
 * \return              The pointer configuration
 
228
 */
 
229
MirPointerConfiguration const* mir_input_device_get_pointer_configuration(
 
230
    MirInputDevice const* device);
 
231
 
 
232
/**
 
233
 * Retrieve the cursor acceleration profile.
 
234
 *
 
235
 * \param [in] conf     The pointer configuration
 
236
 *
 
237
 * \return              The acceleration profile
 
238
 */
 
239
MirPointerAcceleration mir_pointer_configuration_get_acceleration(
 
240
    MirPointerConfiguration const* conf);
 
241
 
 
242
/**
 
243
 * Retrieve the cursor acceleration bias.
 
244
 *
 
245
 * The value will be in the range of [-1, 1]:
 
246
 *   - 0: default acceleration
 
247
 *   - [-1, 0): reduced acceleration
 
248
 *   - (0, 1]: increased acceleration
 
249
 *
 
250
 * \param [in] conf     The pointer configuration
 
251
 *
 
252
 * \return              The acceleration bias
 
253
 */
 
254
double mir_pointer_configuration_get_acceleration_bias(
 
255
    MirPointerConfiguration const* conf);
 
256
 
 
257
/**
 
258
 * Retrieve the horizontal scroll scale.
 
259
 *
 
260
 * The value is a signed linear scale of the horizontal scroll axis. A Negative
 
261
 * value indicates 'natural scrolling'.
 
262
 *
 
263
 * \param [in] conf     The pointer configuration
 
264
 *
 
265
 * \return              The horizontal scroll scale
 
266
 */
 
267
double mir_pointer_configuration_get_horizontal_scroll_scale(
 
268
    MirPointerConfiguration const* conf);
 
269
 
 
270
/**
 
271
 * Retrieve the vertical scroll scale.
 
272
 *
 
273
 * The value is a signed linear scale of the vertical scroll axis. A Negative
 
274
 * value indicates 'natural scrolling'.
 
275
 *
 
276
 * \param [in] conf     The pointer configuration
 
277
 *
 
278
 * \return              The vertical scroll scale
 
279
 */
 
280
double mir_pointer_configuration_get_vertical_scroll_scale(
 
281
    MirPointerConfiguration const* conf);
 
282
 
 
283
/**
 
284
 * Retrieve whether the pointer device is configured for right or left handed
 
285
 * use.
 
286
 *
 
287
 * \param [in] conf     The pointer configuration
 
288
 *
 
289
 * \return              Right or left handed
 
290
 */
 
291
MirPointerHandedness mir_pointer_configuration_get_handedness(
 
292
    MirPointerConfiguration const* conf);
 
293
 
 
294
/**
 
295
 * Retrieve a structure containing the pointer related configuration options
 
296
 * of the input device that can be manipulated.
 
297
 *
 
298
 * If the input device does not control the mouse cursor, there will be no
 
299
 * configuration options, and the function will return a null pointer.
 
300
 *
 
301
 * \param [in] device   The input device
 
302
 *
 
303
 * \return              The pointer configuration
 
304
 */
 
305
MirPointerConfiguration* mir_input_device_get_mutable_pointer_configuration(
 
306
    MirInputDevice* device);
 
307
 
 
308
/**
 
309
 * Set the acceleration mode of the pointer device.
 
310
 *
 
311
 * See \ref MirPointerAcceleration for reference.
 
312
 *
 
313
 * \param [in] conf          The pointer configuration
 
314
 * \param [in] acceleration  The acceleration mode
 
315
 */
 
316
void mir_pointer_configuration_set_acceleration(
 
317
    MirPointerConfiguration* conf,
 
318
    MirPointerAcceleration acceleration);
 
319
 
 
320
/**
 
321
 * Set the acceleration bias of the pointer device.
 
322
 *
 
323
 * The acceleration bias must be in the range of [-1, 1]:
 
324
 *   - 0: default acceleration
 
325
 *   - [-1, 0): reduced acceleration
 
326
 *   - (0, 1]: increased acceleration
 
327
 *
 
328
 * \param [in] conf              The pointer configuration
 
329
 * \param [in] acceleration_bias The acceleration bias 
 
330
 */
 
331
void mir_pointer_configuration_set_acceleration_bias(
 
332
    MirPointerConfiguration* conf,
 
333
    double acceleration_bias);
 
334
 
 
335
/**
 
336
 * Set the horizontal scroll scale.
 
337
 *
 
338
 * The horizontal scroll scale is a signed linear scale of scroll motion along
 
339
 * the horizontal axis. Negative scales can be used to configure 'natural
 
340
 * scrolling'.
 
341
 *
 
342
 * \param [in] conf                    The pointer configuration
 
343
 * \param [in] horizontal_scroll_scale The horizontal scroll scale
 
344
 */
 
345
void mir_pointer_configuration_set_horizontal_scroll_scale(
 
346
    MirPointerConfiguration* conf,
 
347
    double horizontal_scroll_scale);
 
348
 
 
349
/**
 
350
 * Set the vertical scroll scale.
 
351
 *
 
352
 * The vertical scroll scale is a signed linear scale of scroll motion along
 
353
 * the vertical axis. Negative scales can be used to configure 'natural
 
354
 * scrolling'.
 
355
 *
 
356
 * \param [in] conf                    The pointer configuration
 
357
 * \param [in] vertical_scroll_scale The vertical scroll scale
 
358
 */
 
359
void mir_pointer_configuration_set_vertical_scroll_scale(
 
360
    MirPointerConfiguration* conf,
 
361
    double vertical_scroll_scale);
 
362
 
 
363
/**
 
364
 * Configure left and right hand use of the pointer device.
 
365
 *
 
366
 * This configures which buttons will be used as primary and secondary buttons.
 
367
 *
 
368
 * \param [in] conf       The pointer configuration
 
369
 * \param [in] handedness left or right handed use
 
370
 */
 
371
void mir_pointer_configuration_set_handedness(
 
372
    MirPointerConfiguration* conf,
 
373
    MirPointerHandedness handedness);
 
374
 
 
375
/**
 
376
 * Retrieve a structure containing the touchpad related configuration options
 
377
 * of the input device.
 
378
 *
 
379
 * If the input device is not a touchpad this function will return null pointer.
 
380
 *
 
381
 * \param [in] device   The input device
 
382
 *
 
383
 * \return              The touchpad configuration
 
384
 */
 
385
MirTouchpadConfiguration const* mir_input_device_get_touchpad_configuration(
 
386
    MirInputDevice const* device);
 
387
 
 
388
/**
 
389
 * Retrieve the click modes of the touchpad.
 
390
 *
 
391
 * See \ref MirTouchpadClickMode for reference.
 
392
 *
 
393
 * \param [in] conf     The touchpad configuration
 
394
 *
 
395
 * \return              The touchpad click modes
 
396
 */
 
397
MirTouchpadClickModes mir_touchpad_configuration_get_click_modes(
 
398
    MirTouchpadConfiguration const* conf);
 
399
 
 
400
/**
 
401
 * Retrieve the scroll modes of the touchpad.
 
402
 *
 
403
 * See \ref MirTouchpadScrollMode for reference.
 
404
 *
 
405
 * \param [in] conf     The touchpad configuration
 
406
 *
 
407
 * \return              The touchpad click modes
 
408
 */
 
409
MirTouchpadScrollModes mir_touchpad_configuration_get_scroll_modes(
 
410
    MirTouchpadConfiguration const* conf);
 
411
 
 
412
/**
 
413
 * Retrieve the configured button down for button down scroll mode.
 
414
 *
 
415
 * See \ref MirTouchpadScrollMode for reference.
 
416
 *
 
417
 * \param [in] conf     The touchpad configuration
 
418
 *
 
419
 * \return              The touchpad click modes
 
420
 */
 
421
int mir_touchpad_configuration_get_button_down_scroll_button(
 
422
    MirTouchpadConfiguration const* conf);
 
423
 
 
424
/**
 
425
 * Retrieve whether a tap gesture generates pointer button events.
 
426
 *
 
427
 * \param [in] conf     The touchpad configuration
 
428
 *
 
429
 * \return              whether tap to click is enabled
 
430
 */
 
431
bool mir_touchpad_configuration_get_tap_to_click(
 
432
    MirTouchpadConfiguration const* conf);
 
433
 
 
434
/**
 
435
 * Retrieve whether middle mouse button should be emulated.
 
436
 *
 
437
 * \param [in] conf     The touchpad configuration
 
438
 *
 
439
 * \return              whether middle mouse button emulation is enabled
 
440
 */
 
441
bool mir_touchpad_configuration_get_middle_mouse_button_emulation(
 
442
    MirTouchpadConfiguration const* conf);
 
443
 
 
444
/**
 
445
 * Retrieve whether the touchpad should be disabled when an external pointer
 
446
 * device like a mouse is connected.
 
447
 *
 
448
 * \param [in] conf     The touchpad configuration
 
449
 *
 
450
 * \return              whether touchpad is disabled with an external mouse
 
451
 */
 
452
bool mir_touchpad_configuration_get_disable_with_mouse(
 
453
    MirTouchpadConfiguration const* conf);
 
454
 
 
455
/**
 
456
 * Retrieve whether the touchpad events should be blocked while the user types.
 
457
 *
 
458
 * \param [in] conf     The touchpad configuration
 
459
 *
 
460
 * \return              whether touchpad is disabled during typing
 
461
 */
 
462
bool mir_touchpad_configuration_get_disable_while_typing(
 
463
    MirTouchpadConfiguration const* conf);
 
464
 
 
465
/**
 
466
 * Retrieve a structure containing the touchpad related configuration options
 
467
 * of the input device that can be manipulated.
 
468
 *
 
469
 * If the input device is not a touchpad this function will return null pointer.
 
470
 *
 
471
 * \param [in] device   The input device
 
472
 *
 
473
 * \return              A mutable touchpad configuration
 
474
 */
 
475
MirTouchpadConfiguration* mir_input_device_get_mutable_touchpad_configuration(
 
476
    MirInputDevice* device);
 
477
 
 
478
/**
 
479
 * Configure the enable click modes for the touchpad.
 
480
 *
 
481
 * \param [in] conf     The touchpad configuration
 
482
 * \param [in] modes    the enabled click modes
 
483
 */
 
484
void mir_touchpad_configuration_set_click_modes(
 
485
    MirTouchpadConfiguration* conf, MirTouchpadClickModes modes);
 
486
 
 
487
/**
 
488
 * Configure the enabled scroll modes for the touchpad.
 
489
 *
 
490
 * \param [in] conf     The touchpad configuration
 
491
 * \param [in] modes    the enabled scroll modes
 
492
 */
 
493
void mir_touchpad_configuration_set_scroll_modes(
 
494
    MirTouchpadConfiguration* conf, MirTouchpadScrollModes modes);
 
495
 
 
496
/**
 
497
 * Configure the button for button down scroll mode
 
498
 *
 
499
 * \param [in] conf     The touchpad configuration
 
500
 * \param [in] button   the button
 
501
 */
 
502
void mir_touchpad_configuration_set_button_down_scroll_button(
 
503
    MirTouchpadConfiguration* conf, int button);
 
504
 
 
505
/**
 
506
 * Configure whether tap to click should be enabled
 
507
 *
 
508
 * \param [in] conf         The touchpad configuration
 
509
 * \param [in] tap_to_click
 
510
 */
 
511
void mir_touchpad_configuration_set_tap_to_click(
 
512
    MirTouchpadConfiguration* conf, bool tap_to_click);
 
513
 
 
514
/**
 
515
 * Configure whether middle mouse button emulation should be enabled
 
516
 *
 
517
 * \param [in] conf         The touchpad configuration
 
518
 * \param [in] middle_mouse_button_emulation
 
519
 */
 
520
void mir_touchpad_configuration_set_middle_mouse_button_emulation(
 
521
    MirTouchpadConfiguration* conf, bool middle_emulation);
 
522
 
 
523
/**
 
524
 * Configure whether the touchpad should be turned off while a mouse is attached.
 
525
 *
 
526
 * \param [in] conf         The touchpad configuration
 
527
 * \param [in] active       disable touchpad with mouse
 
528
 */
 
529
void mir_touchpad_configuration_set_disable_with_mouse(
 
530
    MirTouchpadConfiguration* conf, bool active);
 
531
 
 
532
/**
 
533
 * Configure whether the touchpad should be turned off while typing
 
534
 *
 
535
 * \param [in] conf         The touchpad configuration
 
536
 * \param [in] active       disable touchpad while typing
 
537
 */
 
538
void mir_touchpad_configuration_set_disable_while_typing(
 
539
    MirTouchpadConfiguration* conf, bool active);
197
540
#ifdef __cplusplus
198
541
}
199
542
#endif