iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIMenuController Class Reference

Options
Deployment Target:

On This Page
Language:

UIMenuController

The singleton UIMenuController instance presents the menu interface for the Cut, Copy, Paste, Select, Select All, and Delete commands.

This menu is referred to as the editing menu. When you make this menu visible, UIMenuController positions it relative to a target rectangle on the screen; this rectangle usually defines a selection. The menu appears above the target rectangle or, if there is not enough space for it, below it. The menu’s pointer is placed at the center of the top or bottom of the target rectangle, as appropriate. Be sure to set the tracking rectangle before you make the menu visible. You are also responsible for detecting, tracking, and displaying selections.

The UIResponderStandardEditActions informal protocol declares methods that are invoked when the user taps a menu command. The canPerformAction:withSender: method of UIResponder is also related to the editing menu. A responder implements this method to enable and disable commands of the editing menu just before the menu is displayed. You can force this updating of menu commands’ enabled state by calling the update method.

You can also provide your own menu items via the menuItems property. When you modify the menu items, you can use the update method to force the menu to update its display.

  • The visibility of the editing menu.

    Declaration

    Swift

    var menuVisible: Bool

    Objective-C

    @property(nonatomic, getter=isMenuVisible) BOOL menuVisible

    Discussion

    Setting this property displays or hides the menu immediately, without animation. For animating the showing or hiding of the menu, use the setMenuVisible:animated: method. Before showing the menu, be sure to position it relative to the selection.

    Availability

    Available in iOS 3.0 and later.

  • Shows or hides the editing menu, optionally animating the action.

    Declaration

    Swift

    func setMenuVisible(_ menuVisible: Bool, animated animated: Bool)

    Objective-C

    - (void)setMenuVisible:(BOOL)menuVisible animated:(BOOL)animated

    Parameters

    menuVisible

    YEStrue if the menu should be shown, NOfalse if it should be hidden.

    animated

    YEStrue if the showing or hiding of the menu should be animated, otherwise NOfalse.

    Discussion

    Before showing the menu, be sure to position it relative to the selection. See setTargetRect:inView: for details. If you do not set the target rect before displaying the menu, it appears at screen coordinates (0.0, 0.0).

    Availability

    Available in iOS 3.0 and later.

    See Also

    menuVisible

  • Sets the area in a view above or below which the editing menu is positioned.

    Declaration

    Swift

    func setTargetRect(_ targetRect: CGRect, inView targetView: UIView)

    Objective-C

    - (void)setTargetRect:(CGRect)targetRect inView:(UIView * nonnull)targetView

    Parameters

    targetRect

    A rectangle that defines the area that is to be the target of the menu commands.

    targetView

    The view in which targetRect appears.

    Discussion

    This target rectangle (targetRect) is usually the bounding rectangle of a selection. UIMenuController positions the editing menu above this rectangle; if there is not enough space for the menu there, it positions it below the rectangle. The menu’s pointer is placed at the center of the top or bottom of the target rectangle as appropriate. Note that if you make the width or height of the target rectangle zero, UIMenuController treats the target area as a line or point for positioning (for example, an insertion caret or a single point).

    Once it is set, the target rectangle does not track the view; if the view moves (such as would happen in a scroll view), you must update the target rectangle accordingly.

    Availability

    Available in iOS 3.0 and later.

    See Also

    menuFrame

  • Returns the frame of the editing menu. (read-only)

    Declaration

    Swift

    var menuFrame: CGRect { get }

    Objective-C

    @property(nonatomic, readonly) CGRect menuFrame

    Discussion

    The property value is the bounding rectangle of the menu in screen coordinates. The property has a value of CGRectZero if the menu is not visible. You can use this property to adjust any user-interface objects away from the menu after displaying the menu.

    Availability

    Available in iOS 3.0 and later.

  • The direction the arrow of the editing menu is pointing.

    Declaration

    Swift

    var arrowDirection: UIMenuControllerArrowDirection

    Objective-C

    @property(nonatomic) UIMenuControllerArrowDirection arrowDirection

    Discussion

    You can set the direction editing-menu arrow points by assigning a UIMenuControllerArrowDirection enum constant to this property. The default behavior (UIMenuControllerArrowDefault) is to point up or down at the object of focus based on its location on the screen.

    Availability

    Available in iOS 3.2 and later.

  • Updates the appearance and enabled state of menu commands.

    Declaration

    Swift

    func update()

    Objective-C

    - (void)update

    Discussion

    By default, UIMenuController calls this method just before the editing menu is made visible and when touches occur in the menu. As a result, a responder object in the application enables or disables menu commands depending on the context; for example, if the pasteboard holds no data of a compatible type, the Paste command would be disabled. You can call this method to force an update of the editing menu. You may also override this method to add any custom behavior.

    Availability

    Available in iOS 3.0 and later.

  • The custom menu items for the editing menu.

    Declaration

    Swift

    var menuItems: [UIMenuItem]?

    Objective-C

    @property(nonatomic, copy) NSArray <UIMenuItem *> *menuItems

    Discussion

    The default value is nil (no custom menu items). Each menu item is an instance of the UIMenuItem class. You may create your own menu items, each with its own title and action selector, and add them to the editing menu through this property. Custom items appear in the menu after any system menu items.

    Availability

    Available in iOS 3.2 and later.

Data Types

  • The direction the arrow of the editing menu is pointing.

    Declaration

    Swift

    enum UIMenuControllerArrowDirection : Int { case Default case Up case Down case Left case Right }

    Objective-C

    typedef enum { UIMenuControllerArrowDefault, UIMenuControllerArrowUp, UIMenuControllerArrowDown, UIMenuControllerArrowLeft, UIMenuControllerArrowRight, } UIMenuControllerArrowDirection;

    Constants

    • Default

      UIMenuControllerArrowDefault

      The arrow is pointing up or down at the object of focus based on its location in the screen.

      Available in iOS 3.2 and later.

    • Up

      UIMenuControllerArrowUp

      The arrow is pointing up at the object of focus.

      Available in iOS 3.2 and later.

    • Down

      UIMenuControllerArrowDown

      The arrow is pointing down at the object of focus.

      Available in iOS 3.2 and later.

    • Left

      UIMenuControllerArrowLeft

      The arrow is pointing left at the object of focus.

      Available in iOS 3.2 and later.

    • Right

      UIMenuControllerArrowRight

      The arrow is pointing right at the object of focus.

      Available in iOS 3.2 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.