Index

API

These are the functions exported by the library.

mousetrap_create creates a new mousetrap with an internally generated id
mousetrap_create_with_id creates a mousetrap with the given id
mousetrap_destroy reclaim the resources used by a mousetrap
mousetrap_get_my_id returns the integer id used by this mousetrap
mousetrap_lookup_id returns the integer id for the item at (x, y)
mousetrap_read_ids returns a list with each unique id read from the specified rectangle in the mousetrap
mousetrap_blit copies one mousetrap into another
mousetrap_copy_rect copy a rectangle from a mousetrap
mousetrap_copy_rect_with_id copy a rectangle from a mousetrap with the given id
mousetrap_dump_compressed prints a textual representation of the compressed mousetrap
mousetrap_dump_uncompressed prints a mousetrap's data in an uncompressed format.
mousetrap_get_next_id returns the next unused integer identifier, could overflow
mousetrap_id_list_destroy frees memory used by an integer list.

Name

Top
mousetrap_create -- creates a new mousetrap with an internally generated id

Synopsis 

#include <mousetrap/mousetrap.h>

mousetrap_t *
mousetrap_create(mt_source_t source_type, unsigned int source_flags, void *source);

Description

Returns a new mousetrap based on the information in source and source_type with an id generated by mousetrap_get_next_id. Returns NULL on failure.

Supported Flags:
The flags depend on the type of source that is used. Consult the supported sources section for documentation.

Name

Top
mousetrap_create_with_id -- creates a mousetrap with a given id

Synopsis 

#include <mousetrap/mousetrap.h>

mousetrap_t *
mousetrap_create_with_id(mt_source_t source_type, unsigned int source_flags,  void *source, unsigned int id);
Returns a new mousetrap based on the information in source with the specified id. Returns NULL on failure.

Supported Flags:
The flags depend on the type of source that is used. Consult the supported sources section for documentation.

Name

Top

mousetrap_destroy -- reclaim the resources used by a mousetrap

Synopsis 

#include <mousetrap/mousetrap.h>

void
mousetrap_destroy(mousetrap_t *trap);

Description:

Frees the resources used by trap.

Name

Top
mousetrap_get_my_id -- returns the integer id used by a mousetrap

Synopsis 

#include <mousetrap/mousetrap.h>

unsigned int
mousetrap_get_my_id(mousetrap_t *trap);

Description

Returns the integer id used by trap which is set when trap is created.

Name

Top
mousetrap_lookup_id -- returns the integer id for the item at (x, y)

Synopsis 

#include <mousetrap/mousetrap.h>

unsigned int
mousetrap_lookup_id(mousetrap_t *trap, int x, int y);

Description

Returns the id associated with the given coordinates x, y in trap. If x or y is outside the area of trap, PLACEHOLDER_ID is returned as a failure value.

Name

Top
mousetrap_read_ids -- returns a linked list with a node for each unique id read from the specified rectangle in the buffer.

Synopsis 

#include <mousetrap/mousetrap.h>

mt_id_list_t *
mousetrap_read_ids(mousetrap_t *trap, int x, int y, int width, int height);

Description

Returns a linked list of all ids contained in the rectangle specified by x, y, width, and height from trap. The rectangle of interest is clipped to trap's boundaries.
The node format of the linked list is in mousetrap.h, the list can be traversed one direction only, via the next pointer member of the node struct. The id can be retrieved from the data member of the node struct. All Reserved IDs are stripped from the return value. Returns NULL on failure.


The return list's memory can be cleaned up by mousetrap_id_list_destroy.
I'd like a more graceful way to handle this. Solutions would be appreciated.

Name

Top
mousetrap_blit -- copies one mousetrap into another

Synopsis 

#include <mousetrap/mousetrap.h>

int
mousetrap_blit(mousetrap_t *dest, mousetrap_t *src, int x, int y, unsigned in t flags);
Copies the mousetrap in src into dest with the upper left corner of src at (x, y) in dest. This permanently alters dest. src is clipped to the boundary of dest. Returns 0 for failure or 1 for success.

Supported Flags:

If MT_NO_TRANSPARENCY is set, the blit copies transparent areas directly into dest (thus making that part of dest transparent). If MT_NO_TRANSPARENCY is not set, transparency support is enabled and gets applied.

Name

Top
mousetrap_copy_rect -- copy a rectangle from a mousetrap

Synopsis 

#include <mousetrap/mousetrap.h>

mousetrap_t *
mousetrap_copy_rect(mousetrap_t *trap, int x, int y, int width, int height);

Description

Returns a copy of a rectangle specified by x, y, width and height from trap. The identifier of the new mousetrap is generated internally (by mousetrap_get_next_id). This function clips to the edges of trap. Returns NULL on failure.

Name

Top
mousetrap_copy_rect_with_id -- copy a rectangle from a mousetrap with a specified id

Synopsis 

#include <mousetrap/mousetrap.h>

mousetrap_t *
mousetrap_copy_rect(mousetrap_t *trap, int x, int y, int width, int height, unsigned int id);

Description

Returns a copy of a rectangle specified by x, y, width and height from trap with the identifier for the mousetrap set as id. This function clips to the edges of trap. Returns NULL on failure.

Name

Top
mousetrap_dump_compressed -- prints a textual representation of the compressed mousetrap

Synopsis 

#include <mousetrap/mousetrap.h>

void
mousetrap_dump_compressed(mousetrap_t *trap);

Description

Prints the mousetrap information in trap to STDOUT in a textual form representing the compressed format of the mousetrap in memory. The buffer width and height, respectively, are printed. The format of the text output depends on the compression type. Consult the compression types documentation for supported compression types and their text formats.

Name

Top
mousetrap_dump_uncompressed -- prints a mousetrap's data in an uncompressed format.

Synopsis 


#include <mousetrap/mousetrap.h>

void
mousetrap_dump_uncompressed(mousetrap_t *trap);

Description

This function prints a mousetrap to STDOUT. The mousetrap is printed as one integer id character for every pixel or point represented. It's mostly useful for debugging and testing, as the id text is not separated by spaces between neighboring pixels and doesn't look very good when the buffer is wider than your terminal.

Name

Top
mousetrap_get_next_id -- returns the next unused integer identifier, could overflow

Synopsis 

#include <mousetrap/mousetrap.h>

unsigned int 
mousetrap_get_next_id();

Description

Returns the next unused, unreserved identifier for creating a unique mask. See also Reserved IDs.

It will overflow when ID is greater than an unsigned int can hold. This is one of the things I'd like a better solution for.

Name

Top
mousetrap_id_list_destroy -- frees memory used by an integer list.

Synopsis 

#include <mousetrap/mousetrap.h>

void mousetrap_id_list_destroy(mt_id_list_t *list);

Description

Frees the memory used by an id list (mt_id_list_t) returned by mousetrap_read_ids.
Copyright © 2001 Ben Smith