Image Processing Toolbox™

impositionrect - Create draggable position rectangle

Syntax

H = impositionrect(hparent,position)

Note This function is obsolete and may be removed in future versions. Use imrect instead.

Description

H = impositionrect(hparent,position) creates a position rectangle on the object specified by hparent. The function returns H, a handle to the position rectangle, which is an hggroup object. hparent specifies the hggroup's parent, which is typically an axes object, but can also be any other object that can be the parent of an hggroup. position is a four-element position vector that specifies the initial location of the rectangle. position has the form [XMIN YMIN WIDTH HEIGHT].

All measurements are in units specified by the Units property axes object.When you do not specify the position argument, impositionrect uses [0 0 1 1] as the default value.

Remarks

A position rectangle can be dragged interactively using the mouse. When the position rectangle occupies a small number of screen pixels, its appearance changes to aid visibility.

The position rectangle has a context menu associated with it that you can use to copy the current position to the clipboard and change the color used to display the rectangle.

API Function Syntaxes

A position rectangle contains a structure of function handles, called an API, that can be used to manipulate it. To retrieve this structure from the position rectangle, use the iptgetapi function.

API = iptgetapi(H)

The following lists the functions in the position rectangle API in the order they appear in the API structure.

Function	Description
`setPosition`	Sets the position rectangle to a new position. api.setPosition(new_position) where `new_position` is a four-element position vector.
`getPosition`	Returns the current position of the position rectangle. position = api.getPosition() `position` is a four-element position vector.
`delete`	Deletes the position rectangle associated with the API. api.delete()
`setColor`	Sets the color used to draw the position rectangle. api.setColor(new_color) where `new_color` can be a three-element vector specifying an RGB triplet, or a text string specifying the long or short names of a predefined color, such as `'white'` or `'w'`. For a complete list of these predefined colors and their short names, see `ColorSpec`.
`addNewPositionCallback`	Adds the function handle fun to the list of new-position callback functions. id = api.addNewPositionCallback(fun) Whenever the position rectangle changes its position, each function in the list is called with the syntax: fun(position) The return value, `id`, is used only with `removeNewPositionCallback`.
`removeNewPositionCallback`	Removes the corresponding function from the new-position callback list. api.removeNewPositionCallback(id) where `id` is the identifier returned by `api.addNewPositionCallback`
`setDragConstraintCallback`	Sets the drag constraint function to be the specified function handle, fcn. api.setDragConstraintCallback(fcn) Whenever the position rectangle is moved because of a mouse drag, the constraint function is called using the syntax: constrained_position = fcn(new_position) where `new_position` is a four-element position vector. This allows a client, for example, to control where the position rectangle may be dragged.

Examples

Display in the command window the updated position of the position rectangle as it moves in the axes.

close all, plot(1:10)
h = impositionrect(gca, [4 4 2 2]);
api = iptgetapi(h);
api.addNewPositionCallback(@(p) disp(p));

Constrain the position rectangle to move only up and down.

close all, plot(1:10)
h = impositionrect(gca, [4 4 2 2]);
api = getappdata(h, 'API');
api.setDragConstraintCallback(@(p) [4 p(2:4)]);

Specify the color of the position rectangle.

close all, plot(1:10)
h = impositionrect(gca, [4 4 2 2]);
api = iptgetapi(h, 'API');
api.setColor([1 0 0]);

When the position rectangle occupies only a few pixels on the screen, the rectangle is drawn in a different style to increase its visibility.