FlowarePopover 0.4

FlowarePopover 0.4

×

由 lam1607 维护。

FlowarePopover 0.4

  • 作者
  • lam1607

FlowarePopover

FlowarePopover，如名称所示，是基于 RBLPopover、NSPopover 和其他库的自定义弹出层，用于在 NSWindow 或 NSView 上显示 NSViewController 或 NSView 弹出窗口。

要求

  • Objective-C
  • macOS 10.11+
  • XCode 8.3+

安装

CocoaPods

CocoaPods 是 Cocoa 项目的依赖管理器。您可以使用以下命令安装它：

$ sudo gem install cocoapods

要在 Xcode 项目中使用 CocoaPods 集成 FlowarePopover，请在 Podfile 中指定它

platform :osx, '10.11'

target '<Your Target Name>' do
  pod 'FlowarePopover'
end

然后，在 <Your Project Directory> 中运行以下命令：

$ pod install

弹出窗口 API

弹出窗口有一些主要 API，如下列所示：

类型

弹出视图有两大类型

  • FLOViewPopover
  • FLOWindowPopover

初始化

  • NSView

    • 默认
      - (id)initWithContentView:(NSView *)contentView;
    • 详细
      - (id)initWithContentView:(NSView *)contentView type:(FLOPopoverType)type;

  • NSViewController

    • 默认
      - (id)initWithContentViewController:(NSViewController *)contentViewController;
    • 详细
      - (id)initWithContentViewController:(NSViewController *)contentViewController type:(FLOPopoverType)type;

FLOPopover类型默认初始化为 FLOWindowPopover

示例:

  popover = [[FLOPopover alloc] initWithContentViewController:self.dataViewController];

属性

  • contentView (只读) : 初始化中设置的内容视图。
  • contentViewController (只读) : 初始化中设置的内容视图控制器。
  • type (只读) : 弹出视图的类型。
  • frame (只读) : 弹出视图的框架。
  • shown (getter = isShown) (只读) : 检查弹出视图是否已经显示。
  • shouldShowArrow : 弹出视图显示箭头（仅在显示在发送视图时可用）
  • animated : 带动画显示弹出视图
  • animatedForwarding : 带有转发方向的动画
  • shouldChangeSizeWhenApplicationResizes : 应用程序窗口大小改变时改变弹出视图的大小
  • closesWhenPopoverResignsKey : 在键被放弃时自动关闭弹出视图
  • closesWhenApplicationBecomesInactive : 应用程序变得不活跃时自动关闭弹出视图
  • closesWhenApplicationResizes : 应用程序大小改变时自动关闭弹出视图
  • closesAfterTimeInterval : 稍过一段时间后自动关闭弹出视图
  • isMovable : 使弹出视图可拖动
  • isDetachable : 使弹出视图可拖动并可断开
  • canBecomeKey : 将弹出视图作为关键窗口（仅对 FLOWindowPopover 有效）
  • tag : 如需要，为弹出视图设置标签

显示

显示中

弹出视图可以使用以下方法显示：

  • 在选定的视图 positioningView 上显示弹出窗口，其框架为选中视图的可视区域边界 rect。这意味着弹出窗口将固定在选中视图上。如果要在弹出窗口上显示箭头，我们应 SHOULD 使用 visibleRect。如果不使用 visibleRect，在某些情况下箭头可能会显示在意外的位置。

      - (void)showRelativeToRect:(NSRect)rect ofView:(NSView *)positioningView edgeType:(FLOPopoverEdgeType)edgeType;

  • 通过给定的框架 rect 在选定的视图 positioningView 相对位置显示弹出窗口。

      - (void)showRelativeToView:(NSView *)positioningView withRect:(NSRect)rect;

  • 通过给定的框架 rect 和相对于 positioningView 的特定相对位置 relativePositionType 显示弹出窗口，以相对于选定的视图 positioningView。

      - (void)showRelativeToView:(NSView *)positioningView withRect:(NSRect)rect relativePositionType:(FLOPopoverRelativePositionType)relativePositionType;

  • 通过给定的框架 rect 相对于选定的视图 positioningView 显示弹出窗口。sender 是触发弹出窗口显示事件的视图。这意味着当我们点击 sender 但我们希望相对于 positioningView 显示弹出窗口时。

      - (void)showRelativeToView:(NSView *)positioningView withRect:(NSRect)rect sender:(NSView *)sender;

  • 通过给定的框架 rect 和相对于 positioningView 的特定相对位置 relativePositionType 显示弹出窗口，sender 是触发弹出窗口显示事件的视图。这意味着当我们点击 sender 但我们希望相对于 positioningView 显示弹出窗口时。

      - (void)showRelativeToView:(NSView *)positioningView withRect:(NSRect)rect sender:(NSView *)sender relativePositionType:(FLOPopoverRelativePositionType)relativePositionType;

注意：rect 必须是屏幕上的一个矩形值（必须通过 [convertRectToScreen:] 方法转换为屏幕矩形）。因此，在显示之前必须将给定的框架转换为屏幕框架。

所有 [showRelativeToView:withRect:]、[showRelativeToView:withRect:relativePositionType:]、[showRelativeToView:withRect:sender:] 方法都执行 [showRelativeToView:withRect:sender:relativePositionType:] 方法。

需要一个 sender。如果您同时使用 [showRelativeToView:withRect:] 和 [showRelativeToView:withRect:relativePositionType:] 方法，则表示 sender 和 positioningView 是相同的。

弹出窗口需要知道发送显示事件的 sender，以避免从 closesWhenPopoverResignsKey 发生的显示问题。当您将 closesWhenPopoverResignsKey 设置为 YES 并再次点击 sender 时。

相对位置 FLOPopoverRelativePositionType 有以下几种类型（弹出窗口相对于 positioningView 的显示方式）

  • FLOPopoverRelativePositionAutomatic：这意味着相对位置（锚点视图约束）将根据给定的框架自动计算
  • FLOPopoverRelativePositionTopLeading
  • FLOPopoverRelativePositionTopTrailing
  • FLOPopoverRelativePositionBottomLeading
  • FLOPopoverRelativePositionBottomTrailing

有关 [showRelativeToView:withRect:]、[showRelativeToView:withRect:relativePositionType:]、[showRelativeToView:withRect:sender:] 和 [showRelativeToView:withRect:sender:relativePositionType:] 方法以及 FLOPopoverRelativePositionType 的更多详细信息，请参阅 github 仓库中的示例并尝试。

示例:

  • 固定矩形：在 positioning view 的可视矩形中相对显示弹出窗口。
      [popover showRelativeToRect:[sender visibleRect] ofView:sender edgeType:FLOPopoverEdgeTypeBelowLeftEdge];
  • 给定矩形：在选定的视图上显示给定矩形中的弹出窗口。
      NSRect positioningRect = [sender.window convertRectToScreen:NSMakeRect(100.0, 200.0, 0.0, 0.0)];

  [popover showRelativeToView:sender withRect:positioningRect];
  • 给定矩形：在选定的视图上以特定相对位置显示给定矩形中的弹出窗口。
      // frame here is screen rect
  NSRect frame = [self calculateMessageBoxFrame];

  [popover showRelativeToView:self.view.window.contentView withRect:frame relativePositionType:FLOPopoverRelativePositionBottomTrailing];
  • 给定矩形：在 given rect 中相对 positioningView 显示弹出窗口，带有 sender。
      NSRect viewRect = [self.view.window convertRectToScreen:[self.view convertRect:self.view.bounds toView:self.view.window.contentView]];
  NSRect popoverRect = sortSelectionController.view.frame;
  popoverRect.origin.x = viewRect.origin.x + viewRect.size.width + 2;
  popoverRect.origin.y = viewRect.origin.y + 1;

  [popover showRelativeToView:self.view withRect:popoverRect sender:selectedCell];

关闭操作

  - (void)close;

示例:

    if ([popover isShown]) {
        [popover close];
    }

弹出窗口边缘类型

显示粘性弹出层时，必须提供边缘类型。弹出层的边缘类型定义为 NS_ENUM 类的 FLOPopoverEdgeType，其值为

  • FLOPopoverEdgeTypeAboveLeftEdge：弹出层将在选定视图的上方显示，弹出层的左边缘将保持在定位矩形的左边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeAboveRightEdge：弹出层将在选定视图的上方显示，弹出层的右边缘将保持在定位矩形的右边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeBelowLeftEdge：弹出层将在选定视图的下方显示，弹出层的左边缘将保持在定位矩形的左边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeBelowRightEdge：弹出层将在选定视图的下方显示，弹出层的右边缘将保持在定位矩形的右边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeBackwardBottomEdge：弹出层将在选定视图的后方显示，弹出层的底部边缘将保持在定位矩形的底部边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeBackwardTopEdge：弹出层将在选定视图的后方显示，弹出层的顶部边缘将保持在定位矩形的顶部边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeForwardBottomEdge：弹出层将在选定视图的前方显示，弹出层的底部边缘将保持在定位矩形的底部边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeForwardTopEdge：弹出层将在选定视图的前方显示，弹出层的顶部边缘将保持在定位矩形的顶部边缘（选定视图的矩形）

  • FLOPopoverEdgeTypeAboveCenter：弹出层将在选定视图的上方显示，弹出层的水平中心点将保持在定位矩形的水平中心点（选定视图的矩形）

  • FLOPopoverEdgeTypeBelowCenter：弹出层将在选定视图的下方显示，弹出层的水平中心点将保持在定位矩形的水平中心点（选定视图的矩形）

  • FLOPopoverEdgeTypeBackwardCenter：弹出层将在选定视图的后方显示，弹出层的垂直中心点将保持在定位矩形的垂直中心点（选定视图的矩形）

  • FLOPopoverEdgeTypeForwardCenter：弹出层将在选定视图的前方显示，弹出层的垂直中心点将保持在定位矩形的垂直中心点（选定视图的矩形）

动画

设置属性 animated 为 YES 后，我们应该使用以下方法在显示时应用动画。

  - (void)setAnimationBehaviour:(FLOPopoverAnimationBehaviour)animationBehaviour type:(FLOPopoverAnimationType)animationType;

或者：

  - (void)setAnimationBehaviour:(FLOPopoverAnimationBehaviour)animationBehaviour type:(FLOPopoverAnimationType)animationType animatedInAppFrame:(BOOL)animatedInAppFrame;

animatedInAppFrame 表示动画仅在应用程序框架内执行。默认情况下，animatedInAppFrame 的值设置为 NO。

动画行为 FLOPopoverAnimationBehaviour 有以下几种类型

  • FLOPopoverAnimationBehaviorDefault (弹出层将使用轻微的默认淡入淡出动画显示)
  • FLOPopoverAnimationBehaviorTransform
  • FLOPopoverAnimationBehaviorTransition

动画类型 FLOPopoverAnimationType 的 FLOPopoverAnimationBehaviour 包含以下类型

  • 默认

    • FLOPopoverAnimationDefault

  • Transform

    • FLOPopoverAnimationScale
    • FLOPopoverAnimationRotate
    • FLOPopoverAnimationFlip

  • Transition

    • FLOPopoverAnimationLeftToRight
    • FLOPopoverAnimationRightToLeft
    • FLOPopoverAnimationTopToBottom
    • FLOPopoverAnimationBottomToTop

示例:

  [popover setAnimationBehaviour:FLOPopoverAnimationBehaviorTransition type:FLOPopoverAnimationRightToLeft];

如果不调用方法 [setAnimationBehaviour:type:]，则默认动画行为和类型将自动执行。

其他工具

当您显示弹出框时，如果您想改变显示在弹出框中的视图或视图控制器的大小和位置，可以使用以下方法。

  • 更新弹出框中视图或视图控制器的内容大小。

      - (void)setPopoverContentViewSize:(NSSize)newSize;

  • 更新弹出框的位置。

      - (void)setPopoverPositioningRect:(NSRect)rect;

  • 在某些情况下，根据需要更新弹出框的位置视图和矩形（不应对此方法用于固定弹出框）。

      - (void)setPopoverPositioningView:(NSView *)positioningView positioningRect:(NSRect)rect;

  • 更新弹出框中视图或视图控制器的内容大小和弹出框的位置。

      - (void)setPopoverContentViewSize:(NSSize)newSize positioningRect:(NSRect)rect;

当您想要更改弹出框中显示的视图或视图控制器时，可以使用以下方法。

  • NSView
  - (void)setPopoverContentView:(NSView *)contentView;
  • NSViewController
  - (void)setPopoverContentViewController:(NSViewController *)contentViewController;

当您使用 FLOWindowPopover 类型显示弹出框并想要更改窗口弹出框的级别时，可以使用此方法。

  - (void)setPopoverLevel:(NSWindowLevel)level;

委托

弹出框使用协议 FLOPopoverDelegate 有以下委托

  - (void)floPopoverWillShow:(FLOPopover *)popover;
  - (void)floPopoverDidShow:(FLOPopover *)popover;
  - (void)floPopoverWillClose:(FLOPopover *)popover;
  - (void)floPopoverDidClose:(FLOPopover *)popover;

如何使用

在您的项目中选择目标屏幕，然后添加以下行

#import <FlowarePopover/FlowarePopover.h>

有关更多用法详情，请查看 GitHub 存储库中的示例。

贡献

请阅读 CONTRIBUTING.md 了解我们的行为准则以及向我们将 pull request 的流程。

作者

  • Floware macOS 团队

许可证

本项目采用 MIT 许可证 - 详细信息请查看 LICENSE.md 文件