PXSourceList 2.0.7

PXSourceList 2.0.7

×

测试已测试✗
语言语言 Obj-CObjective C
许可证 BSD
发布最后发布2015年5月

由Alex Rozanski维护。

PXSourceList 2.0.7

PXSourceList 是一个用于在应用中轻松实现源列表的 NSOutlineView 子类。

PXSourceList 需要 OS X 10.7 SDK 或更高版本，并采用新 BSD 许可证。

PXSourceList in action: The view-based example project included in the repository.

概述

在 OS X 应用中，使用源列表进行导航是一种常见的用户界面范式，但需要大量的手动设置和自定义标准 Cocoa 控件。

PXSourceList 继承了 NSOutlineView 并提供了一个干净的简单 API，来提供源列表的许多常见样式和约定行为。

PXSourceList 有几个关键特性

  • 内置了显示徽章的支持 - 蓝灰色药丸形状，可以显示数值，如特定相册中的照片数量。
  • 始终以“分组样式”显示根级别项目 - 在邮件.app 等应用中使用的 Mail.app 源列表中看到的蓝灰色大写文本。无需额外配置。
  • 通过单个代理方法的实现，支持将特定分组显示为“始终展开”。这些组将始终显示其子项目，并在悬停时不会显示“显示/隐藏”按钮。
  • 由于约定源列表仅使用单列且不显示列头，PXSourceList 只操作单个表列且不显示标题。这在 PXSourceList 的 API 中得到体现，并使得控件更容易使用。
  • 项目包括一个通用数据模型类，可用于构建数据源数据模型，而无需自己编写。

注意，在OS X 人机界面指南中，源列表被细分为那些提供整个应用的导航（具有蓝灰色背景）和那些提供窗口的选中功能（具有白色背景）。PXSourceList 实现了这种第一种类型的源列表；第二种类型不需要太多的常见自定义，所以还不能作为一个独立的控件。

使用 PXSourceList

使用 git 进行克隆

您也可以通过 git 克隆来获得源代码

$ git clone https://github.com/Perspx/PXSourceList.git

然后您可以选择以下方法之一

  • 将 PXSourceList 目录中的所有文件（包括 Internal 子目录中的文件）复制到您的项目中

或者

  • 将 Xcode 项目作为子项目添加到您的 Xcode 项目或工作区中，并针对 PXSourceList 框架目标进行链接。

在您的应用程序中使用 PXSourceList

  1. 将一个 NSOutlineView 对象拖放到您要显示源列表的窗口/视图中。通常源列表放置在一个 NSSplitView 的最左侧面板中。
  2. 在 outline 视图的 Identity 检查器中，将类从 NSOutlineView 占位符更改为 PXSourceList。
  3. 选择（使用 Interface Builder 的 文档大纲 视图会有助于此）源列表（source list），在 Attributes 检查器中“Table View”部分下选择“Highlight”属性为“Source List”。
  4. 控制单击源列表，并将其连接器拖动到您想要成为源列表代理和数据源的对象（选择弹出菜单中的“delegate”或“dataSource”分别），当您释放鼠标按钮时会出现该菜单。源列表 需要 一个数据源对象，但代理是可选的。
  5. 确保导入所需的文件中包含 #import "PXSourceList.h"（此主头文件中导入了代理和数据源协议文件），并确保您的源列表代理和数据源类（class）分别符合 PXSourceListDelegate 和 PXSourceListDataSource 协议。

项目中也包含两个示例项目，以查看如何使用 PXSourceList。

基于单元格模式与基于视图模式

作为 NSOutlineView 的子类，PXSourceList 可以使用单元格（在 基于单元格 模式下）或视图（在 基于视图 模式下）显示其内容。一些代理和数据源方法（见下文）只在 PXSourceList 在基于单元格模式下使用时适用，并在文档中注明。

文档

PXSourceList 及其相关类和协议，使用 appledoc 样式文档对代码仓库中包含的头文件进行了文档说明。

可以通过从 Xcode 项目中构建 Documentation 目标来生成文档（在文档中，它将放在项目的根目录下的 docs 中）。要以这种方式生成文档，必须安装 appledoc（https://github.com/tomaz/appledoc#quick-install），生成文档的脚本期望它在 /usr/local/bin 下安装。

如果您发现任何错误或认为文档的某些部分不够明确或缺失，请 提交 GitHub 问题。

PXSourceList 2

PXSourceList 2 是对 PXSourceList 0.x 和 1.x 的重大改进，它增加了基于视图的表支持，以及许多其他小的改进和错误修复。

为了支持基于视图的表，已添加新的代理和数据源方法，使 PXSourceList 与 NSOutlineView 的 API 保持一致，并实现了一个通用的徽章视图和 NSTableCellView 子类，以允许轻松设置与 PXSourceList 配合使用的 NSTableCellView。

此外，实现了一个通用的 PXSourceListItem 类，无需自己动手编写类即可构建数据源模型。新的内部实现解决了之前版本中某些源列表代理和数据源方法未被调用的问题。

查看 发行说明，以获取更改的全面清单以及版本 2 的 API 变更。

代理和数据源对象

与 NSOutlineView 一样，PXSourceList 对象通过各自的 PXSourceListDataSource 和 PXSourceListDelegate 协议定义的方法，从其 数据源 和 代理 对象获取内容和其他信息。

除了声明新的代理和数据源方法，由于 PXSourceList 是 NSOutlineView 的子类，PXSourceListDataSource 和 PXSourceListDelegate 包括了大多数 NSOutlineViewDelegate 和 NSOutlineViewDataSource 方法，但是将“outlineView”前缀替换为“sourceList”。更多关于实现数据源对象的信息，请参阅 大纲视图编程主题 —— PXSourceList 的代理和数据源实现工作方式非常相似。

请注意，某些 NSOutlineView 的代理和数据源方法与 PXSourceList 不相关，因此没有添加到 PXSourceListDelegate 和 PXSourceListDataSource。

此外，由于 PXSourceList 在底层的工作方式，-[PXSourceList delegate] 和 -[PXSourceList dataSource] 被标记为不可用（它们返回一个内部代理对象）。因此，您应该仅使用 -setDelegate: 和 -setDataSource:。

必需方法

PXSourceList 数据源必须实现以下方法

- (NSUInteger)sourceList:(PXSourceList*)sourceList numberOfChildrenOfItem:(id)item
- (id)sourceList:(PXSourceList*)aSourceList child:(NSUInteger)index ofItem:(id)item
- (BOOL)sourceList:(PXSourceList*)aSourceList isItemExpandable:(id)item

如果您正在使用基于单元格的 PXSourceList，您还需要实现

- (id)sourceList:(PXSourceList*)aSourceList objectValueForItem:(id)item

如果您正在使用基于视图的 PXSourceList，您应该实现

- (NSView *)sourceList:(PXSourceList *)aSourceList viewForItem:(id)item

在您的 代理 对象类中。

请查阅存储库中的基于视图和基于单元格的示例项目，以了解更多关于实现 PXSourceList 代理和数据源对象的信息。

视图基础的源列表

如上所述，PXSourceList 可以在基于单元格或基于视图的模式下使用，以使用单元格或视图显示内容。

当使用基于视图模式的 PXSourceList 时，项目中已包含一些类来帮助为表格中的每个项目设置视图，这是在 PXSourceListDataSource 方法中通过 -sourceList:viewForItem: 实现的。

PXSourceListBadgeView

这是一个视图类，可以绘制带有给定数值的徽章。徽章显示在显示它们的行的右侧，且当包含徽章的行未选择时，背景为灰色蓝色，否则为白色。

PXSourceListTableCellView

这是 NSTableCellView 的子类，它公开了一个 badgeView 出口，可以在 Interface Builder 中将其连接到 PXSourceListBadgeView 实例，然后可以在 -sourceList:viewForItem: 中进行配置。与 NSTableCellView 类似，PXSourceListTableCellView 会自动为您定位 badgeView。

使用 PXSourceListItem 的数据源模型

在 PXSourceList 2 中添加了泛型 PXSourceListItem 类，以创建数据源模型而无需自己编写类。

由于 PXSourceListDataSource 通过构建模型对象的树结构（这与内容的树形表示相映射）工作，因此 PXSourceListItem 允许您使用 children 属性和其他便利方法构建模型对象的树结构。

每个项都可以有

  • 标题。在 -sourceListForItem: 中设置 NSTableCellView 的 textField 属性时很有用。
  • 图标图像。在 -sourceListForItem: 中设置 NSTableCellView 的 imageView 属性时很有用。
  • 标识符。当从 PXSourceList 方法返回时，或者作为 PXSourceListDelegate 或 PXSourceListDataSource 方法的参数时，用于识别特定项很有用。
  • 徽章值。如果您要存储某个特定项的徽章值，而这个项没有后端数据模型对象从那里拉取值时，这个功能非常有用。

此外，每个项都有一个与它相关的 representedObject 属性，这在您不直接在源列表项上设置数据，而是从关联的模型对象中拉取数据时很有用。这意味着您不必保持数据模型和 PXSourceListItem 的属性同步。

致谢

首先感谢所有为该项目做出贡献并帮助其改进的人，修复错误和添加新功能。

在 PXSourceList 的初始版本中，许多来源激发了我的灵感，但特别是 Brandon Walkin 和 Fraser Kuyvenhoven 的 BWToolkit，它给了我如何处理源列表代理和数据源方法的灵感。

Brian Dunagan 在 源列表徽章 和确定各种颜色状态的文章也对我在绘制源列表徽章代码时提供了很大帮助。

Xcode 项目中的 Documentation 目标利用了神奇的 appledoc，这是自 PXSourceList 以来非常宝贵的工具。

示例项目中使用的图标来自由 Yusuke Kamiyamane 创建的 Fugue 图标集（在基于单元格的示例中）和由 Jeremy Salée 创建的 Mimi Glyphs 集合（在基于视图的示例中）。

许可证

PXSourceList 遵循以下详细的 New BSD 许可证（改编自 OSI https://open-source.org.cn/licenses/bsd-license.php）

版权所有 © 2009-14, Alex Rozanski 及其他贡献者。保留所有权利。

在满足以下条件的情况下，允许在原始和二进制形式下重新分配和使用，无论是否修改：

  • 源代码的重新分配必须保留上述版权声明、本条件列表和以下免责声明。
  • 二进制形式的重新分配必须按照与重新分配一样的方式在文档中和/或其他与分配一起提供的材料中重新复制上述版权声明、本条件列表和以下免责声明。
  • 未经特定的先前书面许可，不得使用作者的名字或其贡献者的名字来认可或推广由此软件派生的产品。

本软件由版权所有者和贡献者“按原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性和针对特定目的的适用性的暗示保证。在任何情况下，版权所有者或贡献者不应对任何直接、间接、意外的、特殊的、示范性的或间接的损害（包括但不限于替代商品或服务的采购；使用、数据或利润的丧失；或业务中断）负责，无论该损害是基于合同、严格责任还是侵权（包括疏忽或其他），即使被告知了此类损害的可能性。