From 86083a29334c436e40c1f163c70c7abc285cd98c Mon Sep 17 00:00:00 2001 From: nlogozzo <17648453+nlogozzo@users.noreply.github.com> Date: Mon, 26 Oct 2026 12:18:51 +0000 Subject: [PATCH] chore: Sync SDK bindings --- generator/skipped.txt | 16 +- include/generated/affine_transform.h | 14 - include/generated/alert.h | 2 +- include/generated/apple_event_descriptor.h | 50 -- include/generated/apple_event_manager.h | 12 - include/generated/apple_script.h | 6 - include/generated/archiver.h | 10 +- include/generated/assertion_handler.h | 2 - include/generated/attributed_string.h | 11 - ...tributed_string_markdown_parsing_options.h | 11 - ...tributed_string_markdown_source_position.h | 6 - include/generated/availability.h | 8 - .../generated/background_activity_scheduler.h | 26 +- include/generated/block_operation.h | 2 - include/generated/browser.h | 25 - include/generated/bundle.h | 58 +-- include/generated/byte_count_formatter.h | 39 +- include/generated/cache_base.h | 14 - include/generated/cached_url_response.h | 10 +- include/generated/calendar.h | 55 +-- include/generated/calendar_date.h | 1 - include/generated/character_set.h | 22 - include/generated/class_description.h | 8 - include/generated/clone_command.h | 3 - include/generated/close_command.h | 2 - include/generated/coder.h | 52 +-- include/generated/collection_view_layout.h | 2 +- include/generated/comparison_predicate.h | 9 - include/generated/compound_predicate.h | 7 +- include/generated/condition.h | 7 - include/generated/condition_lock.h | 10 - include/generated/connection.h | 31 -- include/generated/constants.h | 6 - include/generated/control.h | 22 - include/generated/counted_set_base.h | 6 +- include/generated/create_command.h | 3 - include/generated/data_detector.h | 2 - include/generated/date.h | 15 - include/generated/date_components.h | 38 -- include/generated/date_components_formatter.h | 51 +- include/generated/date_formatter.h | 77 +-- include/generated/date_interval.h | 12 +- include/generated/date_interval_formatter.h | 16 +- include/generated/decimal_number.h | 27 +- include/generated/decimal_number_handler.h | 3 +- include/generated/delete_command.h | 3 - include/generated/dimension.h | 4 +- include/generated/directory_enumerator_base.h | 9 +- include/generated/distant_object_request.h | 5 - include/generated/distributed_lock.h | 6 - .../distributed_notification_center.h | 12 - include/generated/energy_formatter.h | 11 - include/generated/enumerator_base.h | 3 - include/generated/enums.h | 211 +-------- include/generated/error.h | 21 +- include/generated/event.h | 9 - include/generated/exception.h | 8 - include/generated/expression.h | 31 -- include/generated/extension_context.h | 5 - include/generated/extension_item.h | 9 - include/generated/file_access_intent.h | 4 - include/generated/file_coordinator.h | 24 +- include/generated/file_handle.h | 34 -- include/generated/file_manager.h | 99 ++-- include/generated/file_provider_service.h | 4 +- include/generated/file_security.h | 2 +- include/generated/file_version.h | 38 +- include/generated/file_wrapper.h | 39 +- include/generated/formatter.h | 6 - include/generated/generated.h | 6 - include/generated/gesture_recognizer.h | 28 +- include/generated/glass_effect_view.h | 22 +- include/generated/hash_table_base.h | 21 +- include/generated/host.h | 9 +- include/generated/http_cookie.h | 36 +- include/generated/http_cookie_storage.h | 26 +- include/generated/httpurl_response.h | 10 +- include/generated/index_path.h | 10 +- include/generated/index_set.h | 30 +- include/generated/index_specifier.h | 3 - include/generated/inflection_rule.h | 4 - include/generated/inflection_rule_explicit.h | 2 - include/generated/input_stream.h | 4 - include/generated/invocation.h | 14 - include/generated/invocation_operation.h | 3 - include/generated/iso8601_date_formatter.h | 10 +- include/generated/item_provider.h | 20 - include/generated/json_serialization.h | 12 +- include/generated/keyed_archiver.h | 17 - include/generated/keyed_unarchiver.h | 21 +- include/generated/length_formatter.h | 11 - include/generated/linguistic_tagger.h | 34 +- include/generated/list_formatter.h | 16 +- include/generated/locale.h | 47 -- include/generated/lock.h | 5 - include/generated/logical_test.h | 1 - include/generated/mach_bootstrap_server.h | 6 - include/generated/mach_port.h | 8 - include/generated/map_table_base.h | 17 +- include/generated/mass_formatter.h | 11 - include/generated/measurement_base.h | 10 +- include/generated/measurement_formatter.h | 20 +- include/generated/menu_item.h | 20 - include/generated/message_port.h | 1 - include/generated/message_port_name_server.h | 4 - include/generated/metadata_item.h | 4 - include/generated/metadata_query.h | 33 -- .../metadata_query_attribute_value_tuple.h | 4 - .../generated/metadata_query_result_group.h | 7 - include/generated/method_signature.h | 8 - include/generated/morphology.h | 9 - include/generated/morphology_custom_pronoun.h | 13 - include/generated/move_command.h | 3 - include/generated/mutable_attributed_string.h | 14 - include/generated/mutable_character_set.h | 27 -- include/generated/mutable_index_set.h | 10 +- include/generated/mutable_paragraph_style.h | 98 +--- include/generated/mutable_url_request.h | 78 ++-- include/generated/name_specifier.h | 3 - include/generated/net_service.h | 42 +- include/generated/net_service_browser.h | 16 +- include/generated/notification.h | 5 +- include/generated/notification_center.h | 10 +- include/generated/notification_queue.h | 5 - include/generated/null.h | 1 - include/generated/number.h | 20 - include/generated/number_formatter.h | 138 ------ include/generated/open_panel.h | 4 - include/generated/operation.h | 22 - include/generated/operation_queue.h | 24 +- .../ordered_collection_change_base.h | 7 - .../ordered_collection_difference_base.h | 6 - include/generated/orthography.h | 13 +- include/generated/output_stream.h | 6 - include/generated/pan_gesture_recognizer.h | 42 +- include/generated/paragraph_style.h | 45 -- include/generated/person_name_components.h | 21 +- .../person_name_components_formatter.h | 21 +- include/generated/pipe.h | 3 - include/generated/pointer_array.h | 15 +- include/generated/pointer_functions.h | 13 - include/generated/port.h | 10 - include/generated/port_coder.h | 4 - include/generated/port_message.h | 7 - include/generated/port_name_server.h | 6 - include/generated/positional_specifier.h | 9 - include/generated/predicate.h | 7 - include/generated/presentation_intent.h | 35 +- include/generated/process_info.h | 40 +- include/generated/progress.h | 103 ++-- .../generated/property_list_serialization.h | 11 +- include/generated/purgeable_data.h | 2 +- include/generated/quit_command.h | 2 - include/generated/range_specifier.h | 5 - include/generated/recursive_lock.h | 5 - include/generated/refresh_controller.h | 152 ------ include/generated/regular_expression.h | 19 +- .../generated/relative_date_time_formatter.h | 28 +- include/generated/relative_specifier.h | 5 - include/generated/responder.h | 2 +- include/generated/run_loop.h | 16 - include/generated/save_panel.h | 4 +- include/generated/scanner.h | 26 -- include/generated/screen.h | 8 - include/generated/script_class_description.h | 35 +- include/generated/script_coercion_handler.h | 4 - include/generated/script_command.h | 25 - .../generated/script_command_description.h | 23 +- include/generated/script_execution_context.h | 8 - include/generated/script_object_specifier.h | 24 +- include/generated/script_suite_registry.h | 28 +- include/generated/script_whose_test.h | 2 - include/generated/scroll_view.h | 83 ---- .../secure_unarchive_from_data_transformer.h | 2 +- include/generated/segmented_control.h | 20 +- include/generated/set_command.h | 3 - include/generated/socket_port.h | 6 - include/generated/socket_port_name_server.h | 10 - include/generated/sort_descriptor.h | 8 - include/generated/specifier_test.h | 1 - include/generated/spell_checker.h | 11 - include/generated/spell_server.h | 8 +- include/generated/status_item.h | 74 +-- .../status_item_expanded_interface_session.h | 51 -- include/generated/stream.h | 11 - include/generated/task.h | 40 +- .../generated/text_attachment_view_provider.h | 9 - include/generated/text_block.h | 68 +-- include/generated/text_checking_result.h | 35 +- include/generated/text_container.h | 60 +-- include/generated/text_content_manager.h | 15 - include/generated/text_content_storage.h | 10 - include/generated/text_element.h | 8 - include/generated/text_field.h | 18 - include/generated/text_layout_fragment.h | 19 - include/generated/text_layout_manager.h | 60 +-- include/generated/text_line_fragment.h | 9 - include/generated/text_list.h | 8 - include/generated/text_list_element.h | 6 - include/generated/text_paragraph.h | 4 - include/generated/text_selection.h | 13 - include/generated/text_selection_manager.h | 185 -------- include/generated/text_selection_navigation.h | 11 - include/generated/text_storage.h | 10 - include/generated/text_tab.h | 11 - include/generated/text_table.h | 7 +- include/generated/text_table_block.h | 3 +- include/generated/text_view.h | 59 --- .../text_viewport_layout_controller.h | 24 - include/generated/thread.h | 24 - include/generated/time_zone.h | 24 - include/generated/timer.h | 12 - .../titlebar_accessory_view_controller.h | 4 +- include/generated/toolbar_item_group.h | 22 +- .../generated/ubiquitous_key_value_store.h | 21 - include/generated/unarchiver.h | 9 +- include/generated/undo_manager.h | 43 +- include/generated/unique_id_specifier.h | 3 - include/generated/unit.h | 3 +- include/generated/unit_acceleration.h | 4 +- include/generated/unit_angle.h | 8 +- include/generated/unit_area.h | 16 +- include/generated/unit_concentration_mass.h | 5 +- include/generated/unit_converter.h | 6 +- include/generated/unit_converter_linear.h | 4 +- include/generated/unit_dispersion.h | 3 +- include/generated/unit_duration.h | 9 +- include/generated/unit_electric_charge.h | 8 +- include/generated/unit_electric_current.h | 7 +- .../unit_electric_potential_difference.h | 7 +- include/generated/unit_electric_resistance.h | 7 +- include/generated/unit_energy.h | 7 +- include/generated/unit_frequency.h | 10 +- include/generated/unit_fuel_efficiency.h | 5 +- include/generated/unit_illuminance.h | 3 +- include/generated/unit_information_storage.h | 35 +- include/generated/unit_length.h | 24 +- include/generated/unit_mass.h | 18 +- include/generated/unit_power.h | 13 +- include/generated/unit_pressure.h | 12 +- include/generated/unit_speed.h | 6 +- include/generated/unit_temperature.h | 5 +- include/generated/unit_volume.h | 33 +- include/generated/url.h | 81 +--- .../generated/url_authentication_challenge.h | 12 +- include/generated/url_cache.h | 30 +- include/generated/url_components.h | 47 +- include/generated/url_connection.h | 13 +- include/generated/url_credential.h | 20 +- include/generated/url_credential_storage.h | 23 +- include/generated/url_download.h | 16 +- include/generated/url_handle.h | 1 - include/generated/url_protection_space.h | 22 +- include/generated/url_protocol.h | 28 +- include/generated/url_query_item.h | 4 - include/generated/url_request.h | 46 +- include/generated/url_response.h | 12 +- include/generated/url_session.h | 60 ++- include/generated/url_session_configuration.h | 103 ++-- include/generated/url_session_data_task.h | 2 +- include/generated/url_session_download_task.h | 4 +- include/generated/url_session_stream_task.h | 14 +- include/generated/url_session_task.h | 50 +- include/generated/url_session_task_metrics.h | 5 +- .../url_session_task_transaction_metrics.h | 56 +-- include/generated/url_session_upload_task.h | 2 +- .../generated/url_session_web_socket_task.h | 16 +- include/generated/user_activity.h | 64 ++- include/generated/user_apple_script_task.h | 2 +- include/generated/user_automator_task.h | 4 +- include/generated/user_defaults.h | 65 ++- include/generated/user_notification.h | 39 -- include/generated/user_notification_action.h | 4 - include/generated/user_notification_center.h | 10 - include/generated/user_script_task.h | 3 +- include/generated/user_unix_task.h | 8 +- include/generated/uuid.h | 10 +- include/generated/value.h | 8 +- include/generated/value_transformer.h | 8 - include/generated/view.h | 119 +---- include/generated/view_corner_configuration.h | 182 -------- include/generated/view_corner_radii.h | 71 --- include/generated/view_corner_radius.h | 73 --- include/generated/whose_specifier.h | 11 - include/generated/writing_tools_coordinator.h | 35 +- include/generated/xml_document.h | 54 ++- include/generated/xml_element.h | 50 +- include/generated/xml_node.h | 93 ++-- include/generated/xml_parser.h | 18 - include/generated/xmldtd.h | 32 +- include/generated/xmldtd_node.h | 20 +- include/generated/xpc_coder.h | 6 - include/generated/xpc_connection.h | 26 -- include/generated/xpc_interface.h | 8 - include/generated/xpc_listener.h | 8 - include/generated/xpc_listener_endpoint.h | 1 - src/generated/application.mm | 4 +- src/generated/browser.mm | 61 --- src/generated/constants.mm | 12 - src/generated/control.mm | 22 - src/generated/event.mm | 12 - src/generated/file_promise_provider.mm | 4 +- src/generated/gesture_recognizer.mm | 23 - src/generated/glass_effect_view.mm | 23 - src/generated/menu_item.mm | 23 - src/generated/mutable_paragraph_style.mm | 46 -- src/generated/pan_gesture_recognizer.mm | 46 -- src/generated/paragraph_style.mm | 23 - src/generated/refresh_controller.mm | 146 ------ src/generated/screen.mm | 12 - src/generated/scroll_view.mm | 104 ----- src/generated/segmented_control.mm | 23 - src/generated/spell_checker.mm | 11 - src/generated/status_item.mm | 121 ----- .../status_item_expanded_interface_session.mm | 31 -- src/generated/text_block.mm | 70 +-- src/generated/text_container.mm | 41 -- src/generated/text_field.mm | 23 - src/generated/text_layout_manager.mm | 41 -- src/generated/text_selection_manager.mm | 438 ------------------ src/generated/text_tab.mm | 18 - src/generated/text_table.mm | 8 +- src/generated/text_table_block.mm | 2 +- src/generated/text_view.mm | 67 --- .../text_viewport_layout_controller.mm | 55 --- src/generated/toolbar_item_group.mm | 23 - src/generated/url_session_task.mm | 24 +- src/generated/view.mm | 109 ----- src/generated/view_corner_configuration.mm | 164 ------- src/generated/view_corner_radii.mm | 68 --- src/generated/view_corner_radius.mm | 56 --- src/generated/writing_tools_coordinator.mm | 38 -- 332 files changed, 1143 insertions(+), 7318 deletions(-) delete mode 100644 include/generated/refresh_controller.h delete mode 100644 include/generated/status_item_expanded_interface_session.h delete mode 100644 include/generated/text_selection_manager.h delete mode 100644 include/generated/view_corner_configuration.h delete mode 100644 include/generated/view_corner_radii.h delete mode 100644 include/generated/view_corner_radius.h delete mode 100644 src/generated/refresh_controller.mm delete mode 100644 src/generated/status_item_expanded_interface_session.mm delete mode 100644 src/generated/text_selection_manager.mm delete mode 100644 src/generated/view_corner_configuration.mm delete mode 100644 src/generated/view_corner_radii.mm delete mode 100644 src/generated/view_corner_radius.mm diff --git a/generator/skipped.txt b/generator/skipped.txt index 5a4bae33..ce804283 100644 --- a/generator/skipped.txt +++ b/generator/skipped.txt @@ -43,7 +43,7 @@ deprecated: 535 NSCell.setEntryType: ... -unavailable/deprecated: 98 +unavailable/deprecated: 101 NSAppearance.currentAppearance NSApplication.context NSBox.borderType @@ -129,7 +129,7 @@ duplicate constructor signature: 76 NSIndexSet.indexSetWithIndexesInRange: ... -unavailable: 66 +unavailable: 65 NSAlert.alertWithMessageText:defaultButton:alternateButton:otherButton:informativeTextWithFormat: NSBitmapImageRep.initWithFocusedViewRect: NSCachedImageRep.initWithSize:depth:separate:alpha: @@ -158,7 +158,6 @@ unavailable: 66 NSSpeechSynthesizer.initWithVoice: NSTextFieldCell.initImageCell: NSTextListElement.initWithAttributedString: - NSTextViewportLayoutController.renderingSurfaceForKey: NSWindow.initWithWindowRef: NSUnarchiver.objectZone NSUnarchiver.setObjectZone: @@ -170,9 +169,10 @@ unavailable: 66 NSBundle.setPreservationPriority:forTags: NSCalendarDate.initWithString: NSCalendarDate.initWithString:calendarFormat: + NSCalendarDate.initWithString:calendarFormat:locale: ... -skipped selector: 49 +skipped selector: 45 NSCollectionViewCompositionalLayout.new NSCollectionLayoutSection.new NSCollectionLayoutItem.new @@ -195,12 +195,8 @@ skipped selector: 49 NSTextRange.new NSTextSelectionNavigation.new NSTextViewportLayoutController.new - NSViewCornerConfiguration.new - NSViewCornerRadii.new - NSViewCornerRadius.new NSViewLayoutRegion.new NSBundle.load - NSError.new NSKeyValueSharedObserversSnapshot.new NSKeyValueSharedObservers.new NSLocalizedNumberFormatRule.new @@ -213,6 +209,10 @@ skipped selector: 49 NSURLSessionDownloadTask.new NSURLSessionStreamTask.new NSURLSessionWebSocketMessage.new + NSURLSessionWebSocketTask.new + NSURLSessionConfiguration.new + NSURLSessionTaskTransactionMetrics.new + NSURLSessionTaskMetrics.new ... unmapped pointer: 11 diff --git a/include/generated/affine_transform.h b/include/generated/affine_transform.h index 77c075cc..b6f45286 100644 --- a/include/generated/affine_transform.h +++ b/include/generated/affine_transform.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSAffineTransform` (Foundation). - * @details A graphics coordinate transformation. In Swift, this object bridges to ''AffineTransform''; use ''NSAffineTransform'' when you need reference semantics or other Foundation-specific behavior. A transformation specifies how points in one coordinate system are transformed to points in another coordinate system. An affine transformation is a special type of transformation that preserves parallel lines in a path but does not necessarily preserve lengths or angles. Scaling, rotation, and translation are the most commonly used manipulations supported by affine transforms, but shearing is also possible. > Note: > In OS X 10.3 and earlier the ''NSAffineTransform'' class was declared and implemented entirely in the Application Kit framework. As of macOS 10.4 the ''NSAffineTransform'' class has been split across the Foundation and Application Kit frameworks. Methods for applying affine transformations to the current graphics context and a method for applying an affine transformation to an \ object are described in NSAffineTransform Additions Reference in the Application Kit. > Important: > The Swift overlay to the Foundation framework provides the ''AffineTransform'' structure, which bridges to the ''NSAffineTransform'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,7 +43,6 @@ namespace cocoon explicit AffineTransform(Adopt adopt); /** * @brief Calls `-[NSAffineTransform appendTransform:]`. - * @details Appends the specified matrix to the receiver's matrix. This method multiplies the receiver's matrix by the matrix in 'transform' and replaces the receiver's matrix with the results. This type of operation is the same as applying the transformations in the receiver followed by the transformations in 'transform'. - Parameter transform: The matrix to append to the receiver. * @param transform Argument converted to the Objective-C parameter of the same role. */ void append_transform(const AffineTransform& transform) const; @@ -54,36 +52,30 @@ namespace cocoon void concat() const; /** * @brief Calls `-[NSAffineTransform invert]`. - * @details Replaces the receiver's matrix with its inverse matrix. Inverse matrices are useful for undoing the effects of a matrix. If a previous point (x,y) was transformed to (x',y'), inverting the matrix and applying it to point (x',y') yields the point (x,y). You can also use inverse matrices in conjunction with the 'concat()' method to remove the effects of concatenating the matrix to the current transformation matrix of the current graphic context. */ void invert() const; /** * @brief Calls `-[NSAffineTransform prependTransform:]`. - * @details Prepends the specified matrix to the receiver's matrix. This method multiplies the matrix in 'transform' by the receiver's matrix and replaces the receiver's matrix with the result. This type of operation is the same as applying the transformations in 'transform' followed by the transformations in the receiver. - Parameter transform: The matrix to prepend to the receiver. * @param transform Argument converted to the Objective-C parameter of the same role. */ void prepend_transform(const AffineTransform& transform) const; /** * @brief Calls `-[NSAffineTransform rotateByDegrees:]`. - * @details Applies a rotation factor (measured in degrees) to the receiver's transformation matrix. After invoking this method, applying the receiver's matrix turns the axes counterclockwise about the current origin by 'angle' degrees, in addition to performing all previous transformations. - Parameter angle: The rotation angle, measured in degrees. * @param angle Argument converted to the Objective-C parameter of the same role. */ void rotate_by_degrees(double angle) const; /** * @brief Calls `-[NSAffineTransform rotateByRadians:]`. - * @details Applies a rotation factor (measured in radians) to the receiver's transformation matrix. After invoking this method, applying the receiver's matrix turns the axes counterclockwise about the current origin by 'angle' radians, in addition to performing all previous transformations. - Parameter angle: The rotation angle, measured in radians. * @param angle Argument converted to the Objective-C parameter of the same role. */ void rotate_by_radians(double angle) const; /** * @brief Calls `-[NSAffineTransform scaleBy:]`. - * @details Applies the specified scaling factor along both x and y axes to the receiver's transformation matrix. After invoking this method, applying the receiver's matrix modifies the unit lengths along the current x and y axes by a factor of 'scale', in addition to performing all previous transformations. - Parameter scale: The scaling factor to apply to both axes. Specifying a negative value has the effect of inverting the direction of the axes in addition to scaling them. A scaling factor of 1.0 scales the content to exactly the same size. * @param scale Argument converted to the Objective-C parameter of the same role. */ void scale_by(double scale) const; /** * @brief Calls `-[NSAffineTransform scaleXBy:yBy:]`. - * @details Applies scaling factors to each axis of the receiver's transformation matrix. After invoking this method, applying the receiver's matrix modifies the unit length on the x axis by a factor of 'scaleX' and the y axis by a factor of 'scaleY', in addition to performing all previous transformations. A value of 1.0 for either axis scales the content on that axis to the same size. - Parameter scaleX: The scaling factor to apply to the x axis. - Parameter scaleY: The scaling factor to apply to the y axis. * @param scale_x Argument converted to the Objective-C parameter of the same role. * @param scale_y Argument converted to the Objective-C parameter of the same role. */ @@ -94,7 +86,6 @@ namespace cocoon void set() const; /** * @brief Calls `+[NSAffineTransform transform]`. - * @details Creates a new affine transform initialized to the identity matrix. - Returns: A new identity transform object. This matrix transforms any point to the same point. * @return The converted Objective-C result. */ static AffineTransform transform(); @@ -106,34 +97,29 @@ namespace cocoon BezierPath transform_bezier_path(const BezierPath& path) const; /** * @brief Calls `-[NSAffineTransform transformPoint:]`. - * @details Applies the receiver's transform to the specified point and returns the result. - Parameter aPoint: The point in the current coordinate system to which you want to apply the matrix. - Returns: The resulting point after applying the receiver's transformations. * @param a_point Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Point transform_point(const Point& a_point) const; /** * @brief Calls `-[NSAffineTransform transformSize:]`. - * @details Applies the receiver's transform to the specified size and returns the results. This method applies the current rotation and scaling factors to 'aSize'; it does not apply translation factors. You can think of this method as transforming a vector whose origin is (0, 0) and whose end point is specified by the value in 'aSize'. After the rotation and scaling factors are applied, this method effectively returns the end point of the new vector. This method is useful for transforming delta or distance values when you need to take scaling and rotation factors into account. - Parameter aSize: The size data to which you want to apply the matrix. - Returns: The resulting size after applying the receiver's transformations. * @param a_size Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Size transform_size(const Size& a_size) const; /** * @brief Calls `-[NSAffineTransform translateXBy:yBy:]`. - * @details Applies the specified translation factors to the receiver's transformation matrix. Subsequent transformations cause coordinates to be shifted by 'deltaX' units along the x axis and by 'deltaY' units along the y axis. Translation factors do not affect 'NSSize' values, which specify a differential between points. - Parameter deltaX: The number of units to move along the x axis. - Parameter deltaY: The number of units to move along the y axis. * @param delta_x Argument converted to the Objective-C parameter of the same role. * @param delta_y Argument converted to the Objective-C parameter of the same role. */ void translate_x_by(double delta_x, double delta_y) const; /** * @brief Returns the `transformStruct` property of `NSAffineTransform`. - * @details The matrix coefficients stored as the transformation matrix. The ''NSAffineTransformStruct'' structure is an alternate representation of a transformation matrix that can be used to specify matrix values directly. The six-element structure is of the form '{m11, m12, m21, m22, tX, tY}'. * @return The converted Objective-C result. */ AffineTransformStruct transform_struct() const; /** * @brief Sets the `transformStruct` property of `NSAffineTransform`. - * @details The matrix coefficients stored as the transformation matrix. The ''NSAffineTransformStruct'' structure is an alternate representation of a transformation matrix that can be used to specify matrix values directly. The six-element structure is of the form '{m11, m12, m21, m22, tX, tY}'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_transform_struct(const AffineTransformStruct& value) const; diff --git a/include/generated/alert.h b/include/generated/alert.h index f671c70c..7a80aea6 100644 --- a/include/generated/alert.h +++ b/include/generated/alert.h @@ -57,7 +57,7 @@ namespace cocoon explicit Alert(Adopt adopt); /** * @brief Calls `-[NSAlert addButtonWithTitle:]`. - * @details Adds a button with a given title to the alert. Buttons should be added from most-to-least prominent. The exact visual arrangement of the buttons is determined by 'NSAlert' internally. In general, they are arranged from trailing-to-leading edge when laid out horizontally, and top-to-bottom when laid out vertically, with some exceptions for buttons like “Cancel”. The first three buttons are identified by the order in which they are added (not the order in which they may appear visually) as 'NSAlertFirstButtonReturn', 'NSAlertSecondButtonReturn', 'NSAlertThirdButtonReturn' in the return-code parameter. Subsequent buttons are identified as 'NSAlertThirdButtonReturn' + n, where n is an integer. By default, the first button has a key equivalent of Return, any button with a title of “Cancel” has a key equivalent of Escape, and any button with the title “Don’t Save” has a key equivalent of Command-D (but only if it’s not the first button). You can also assign different key equivalents for the buttons using the 'keyEquivalent' method of the 'NSButton' class. You can use the 'tag' property of the 'NSButton' class to set the alert presentation’s return-code. Alert button properties that are valid to customize are: - 'keyEquivalent' - 'keyEquivalentModifierMask' - 'tag' - 'hasDestructiveAction' - 'enabled' - 'title' Other button properties are not supported in alert contexts. The framework reserves the use of the button’s 'target' and 'action'. - Parameter title: Title of the button to add to the alert. - Returns: The button that was added to the alert. + * @details Adds a button with a given title to the alert. Buttons should be added from most-to-least prominent. The exact visual arrangement of the buttons is determined by 'NSAlert' internally. In general, they are arranged from trailing-to-leading edge when laid out horizontally, and top-to-bottom when laid out vertically, with some exceptions for buttons like “Cancel”. The first three buttons are identified by the order in which they are added (not the order in which they may appear visually) as 'NSAlertFirstButtonReturn', 'NSAlertSecondButtonReturn', 'NSAlertThirdButtonReturn' in the return-code parameter. Subsequent buttons are identified as 'NSAlertThirdButtonReturn' + n, where n is an integer. By default, the first button has a key equivalent of Return, any button with a title of “Cancel” has a key equivalent of Escape, and any button with the title “Don’t Save” has a key equivalent of Command-D (but only if it’s not the first button). You can also assign different key equivalents for the buttons using the 'keyEquivalent' method of the 'NSButton' class. In addition, you can use the 'tag' property of the 'NSButton' class to set the alert presentation’s return-code. The framework reserves the use of the button’s 'target' and 'action'. - Parameter title: Title of the button to add to the alert. - Returns: The button that was added to the alert. * @param title Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ diff --git a/include/generated/apple_event_descriptor.h b/include/generated/apple_event_descriptor.h index 28953b92..14679b7b 100644 --- a/include/generated/apple_event_descriptor.h +++ b/include/generated/apple_event_descriptor.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSAppleEventDescriptor` (Foundation). - * @details A wrapper for the Apple event descriptor data type. An instance of ''NSAppleEventDescriptor'' represents a descriptor—the basic building block for Apple events. This class is a wrapper for the underlying Apple event descriptor data type, \. Scriptable Cocoa applications frequently work with instances of ''NSAppleEventDescriptor'', but should rarely need to work directly with the \ data structure. A descriptor is a data structure that stores data and an accompanying four-character code. A descriptor can store a value, or it can store a list of other descriptors (which may also be lists). All the information in an Apple event is stored in descriptors and lists of descriptors, and every Apple event is itself a descriptor list that matches certain criteria. > Important: > An instance of 'NSAppleEventDescriptor' can represent any kind of descriptor, from a simple value descriptor, to a descriptor list, to a full-fledged Apple event. Descriptors can be used to build arbitrarily complex containers, so that one Apple event can represent a script statement such as 'tell application "TextEdit" to get word 3 of paragraph 6 of document 3'. In working with Apple event descriptors, it can be useful to understand some of the underlying data types. You'll find terms such as descriptor, descriptor list, Apple event record, and Apple event defined in Building an Apple Event in Apple Events Programming Guide. You'll also find information on the four-character codes used to identify information within a descriptor. Apple event data types are defined in \. The values of many four-character codes used by Apple (and in some cases reused by developers) can be found in [AppleScript Terminology and Apple Event Codes](http://developer.apple.com/releasenotes/AppleScript/ASTerminology_AppleEventCodes/TermsAndCodes.html). The most common reason to construct an Apple event with an instance of 'NSAppleEventDescriptor' is to supply information in a return Apple event. The most common situation where you might need to extract information from an Apple event (as an instance of 'NSAppleEventDescriptor') is when an Apple event handler installed by your application is invoked, as described in "Installing an Apple Event Handler" in [How Cocoa Applications Handle Apple Events](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_handle_AEs/SAppsHandleAEs.html\#//apple_ref/doc/uid/20001239). In addition, if you execute an AppleScript script using the 'NSAppleScript' class, you get an instance of 'NSAppleEventDescriptor' as the return value, from which you can extract any required information. When you work with an instance of 'NSAppleEventDescriptor', you can access the underlying descriptor directly, if necessary, with the ''aeDesc'' method. Other methods, including ''descriptorWithDescriptorType:bytes:length:'' make it possible to create and initialize instances of 'NSAppleEventDescriptor' without creating temporary instances of 'NSData'. The designated initializer for 'NSAppleEventDescriptor' is ''init(aeDescNoCopy:)''. However, it is unlikely that you will need to create a subclass of 'NSAppleEventDescriptor'. Cocoa doesn't currently provide a mechanism for applications to directly send raw Apple events (though compiling and executing an AppleScript script with 'NSAppleScript' may result in Apple events being sent). However, Cocoa applications have full access to the Apple Event Manager C APIs for working with Apple events. So, for example, you might use an instance of 'NSAppleEventDescriptor' to assemble an Apple event and call the Apple Event Manager function 'AESend(:::::::)' to send it. If you need to send Apple events, or if you need more information on some of the Apple event concepts described here, see Apple Events Programming Guide and \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -54,7 +53,6 @@ namespace cocoon explicit AppleEventDescriptor(Adopt adopt); /** * @brief Calls `+[NSAppleEventDescriptor appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:]`. - * @details Creates a descriptor that represents an Apple event, initialized according to the specified information. - Parameters: - eventClass: The event class to be set in the returned descriptor. - eventID: The event ID to be set in the returned descriptor. - targetDescriptor: A pointer to a descriptor that identifies the target application for the Apple event. Passing 'nil' results in an Apple event descriptor that has no 'keyAddressAttr' attribute (it is valid for an Apple event to have no target address attribute). - returnID: The return ID to be set in the returned descriptor. If you pass a value of 'kAutoGenerateReturnID', the Apple Event Manager assigns the created Apple event a return ID that is unique to the current session. If you pass any other value, the Apple Event Manager assigns that value for the ID. - transactionID: The transaction ID to be set in the returned descriptor. A transaction is a sequence of Apple events that are sent back and forth between client and server applications, beginning with the client's initial request for a service. All Apple events that are part of a transaction must have the same transaction ID. You can specify 'kAnyTransactionID' if the Apple event is not one of a series of interdependent Apple events. - Returns: A descriptor for an Apple event, initialized according to the specified parameter values, or 'nil' if an error occurs. Constants such as 'kAutoGenerateReturnID' and 'kAnyTransactionID' are defined in 'AE.framework', a subframework of 'ApplicationServices.framework'. * @param event_class Argument converted to the Objective-C parameter of the same role. * @param event_id Argument converted to the Objective-C parameter of the same role. * @param target_descriptor Argument converted to the Objective-C parameter of the same role. @@ -65,69 +63,59 @@ namespace cocoon static AppleEventDescriptor apple_event_with_event_class(unsigned int event_class, unsigned int event_id, const AppleEventDescriptor& target_descriptor, std::int16_t return_id, int transaction_id); /** * @brief Calls `-[NSAppleEventDescriptor attributeDescriptorForKeyword:]`. - * @details Returns a descriptor for the receiver's Apple event attribute identified by the specified keyword. - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to obtain. - Returns: The attribute descriptor for the specified keyword, or 'nil' if an error occurs. The receiver must be an Apple event. * @param keyword Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor attribute_descriptor_for_keyword(unsigned int keyword) const; /** * @brief Calls `-[NSAppleEventDescriptor coerceToDescriptorType:]`. - * @details Returns a descriptor obtained by coercing the receiver to the specified type. - Parameter descriptorType: The descriptor type to coerce the receiver to. - Returns: A descriptor of the specified type, or 'nil' if an error occurs. * @param descriptor_type Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor coerce_to_descriptor_type(unsigned int descriptor_type) const; /** * @brief Calls `+[NSAppleEventDescriptor currentProcessDescriptor]`. - * @details Creates and returns an application address descriptor using the current process. The result is suitable for use as the 'targetDescriptor' parameter of '+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:'. * @return The converted Objective-C result. */ static AppleEventDescriptor current_process_descriptor(); /** * @brief Calls `-[NSAppleEventDescriptor descriptorAtIndex:]`. - * @details Returns the descriptor at the specified (one-based) position in the receiving descriptor list. - Parameter index: The one-based descriptor list position of the descriptor to return. - Returns: The descriptor from the specified position (one-based) in the descriptor list, or 'nil' if the specified descriptor cannot be obtained. * @param index Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor descriptor_at_index(std::int64_t index) const; /** * @brief Calls `-[NSAppleEventDescriptor descriptorForKeyword:]`. - * @details Returns the receiver's descriptor for the specified keyword. - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to obtain. - Returns: A descriptor for the specified keyword, or 'nil' if an error occurs. * @param keyword Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor descriptor_for_keyword(unsigned int keyword) const; /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithApplicationURL:]`. - * @details Creates and returns an application address descriptor using the specified application URL. The result is suitable for use as the 'targetDescriptor' parameter of '+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:'. * @param application_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_application_url(const URL& application_url); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithBoolean:]`. - * @details Creates a descriptor initialized with type 'typeBoolean' that stores the specified Boolean value. - Parameter boolean: The Boolean value to be set in the returned descriptor. - Returns: A descriptor with the specified Boolean value, or 'nil' if an error occurs. * @param boolean Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_boolean(std::uint8_t boolean); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithBundleIdentifier:]`. - * @details Creates and returns an application address descriptor using the specified bundle identifier. The result is suitable for use as the 'targetDescriptor' parameter of '+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:'. * @param bundle_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_bundle_identifier(const std::string& bundle_identifier); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithDate:]`. - * @details Creates a descriptor that stores the specified date value. * @param date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_date(const Date& date); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithDescriptorType:bytes:length:]`. - * @details Creates a descriptor initialized with the specified event type that stores the specified data (from a series of bytes). - Parameters: - descriptorType: The descriptor type to be set in the returned descriptor. - bytes: The data, as a sequence of bytes, to be set in the returned descriptor. - byteCount: The length, in bytes, of the data to be set in the returned descriptor. - Returns: A descriptor with the specified type and data, or 'nil' if an error occurs. * @param descriptor_type Argument converted to the Objective-C parameter of the same role. * @param bytes Argument converted to the Objective-C parameter of the same role. * @param byte_count Argument converted to the Objective-C parameter of the same role. @@ -136,7 +124,6 @@ namespace cocoon static AppleEventDescriptor descriptor_with_descriptor_type(unsigned int descriptor_type, const void* bytes, std::uint64_t byte_count); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithDescriptorType:data:]`. - * @details Creates a descriptor initialized with the specified event type that stores the specified data (from an instance of 'NSData'). - Parameters: - descriptorType: The descriptor type to be set in the returned descriptor. - data: The data, as an instance of 'NSData', to be set in the returned descriptor. - Returns: A descriptor with the specified type and data, or 'nil' if an error occurs. You can use this method to create a descriptor that you can build into a complete Apple event by calling methods such as '-setAttributeDescriptor:forKeyword:', '-setDescriptor:forKeyword:', and '-setParamDescriptor:forKeyword:'. * @param descriptor_type Argument converted to the Objective-C parameter of the same role. * @param data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -144,113 +131,96 @@ namespace cocoon static AppleEventDescriptor descriptor_with_descriptor_type(unsigned int descriptor_type, const std::vector& data); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithDouble:]`. - * @details Creates a descriptor initialized with Apple event type 'typeIEEE64BitFloatingPoint' that stores the specified double value. * @param double_value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_double(double double_value); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithEnumCode:]`. - * @details Creates a descriptor initialized with type 'typeEnumerated' that stores the specified enumerator data type value. - Parameter enumerator: A type code that identifies the type of enumerated data to be stored in the returned descriptor. - Returns: A descriptor with the specified enumerator data type value, or 'nil' if an error occurs. * @param enumerator Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_enum_code(unsigned int enumerator); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithFileURL:]`. - * @details Creates a descriptor that stores the specified file URL. * @param file_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_file_url(const URL& file_url); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithInt32:]`. - * @details Creates a descriptor initialized with Apple event type 'typeSInt32' that stores the specified integer value. - Parameter signedInt: The integer value to be stored in the returned descriptor. - Returns: A descriptor containing the specified integer value, or 'nil' if an error occurs. * @param signed_int Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_int32(int signed_int); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithProcessIdentifier:]`. - * @details Creates and returns an application address descriptor using the specified process identifier. The result is suitable for use as the 'targetDescriptor' parameter of '+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:'. * @param process_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_process_identifier(int process_identifier); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithString:]`. - * @details Creates a descriptor initialized with type 'typeUnicodeText' that stores the text from the specified string. - Parameter string: A string that specifies the text to be stored in the returned descriptor. - Returns: A descriptor that contains the text from the specified string, or 'nil' if an error occurs. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_string(const std::string& string); /** * @brief Calls `+[NSAppleEventDescriptor descriptorWithTypeCode:]`. - * @details Creates a descriptor initialized with type 'typeType' that stores the specified type value. - Parameter typeCode: The type value to be set in the returned descriptor. - Returns: A descriptor with the specified type, or 'nil' if an error occurs. * @param type_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static AppleEventDescriptor descriptor_with_type_code(unsigned int type_code); /** * @brief Calls `-[NSAppleEventDescriptor insertDescriptor:atIndex:]`. - * @details Inserts a descriptor at the specified (one-based) position in the receiving descriptor list, replacing the existing descriptor, if any, at that position. - Parameters: - descriptor: The descriptor to insert in the receiver. Specifying an index of 0 or count + 1 causes appending to the end of the list. - index: The one-based descriptor list position at which to insert the descriptor. Because it actually replaces the descriptor, if any, at the specified position, this method might better be called 'replaceDescriptor:atIndex:'. The receiver must be a list descriptor. The indices are one-based. Currently provides no indication if an error occurs. * @param descriptor Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_descriptor(const AppleEventDescriptor& descriptor, std::int64_t index) const; /** * @brief Calls `-[NSAppleEventDescriptor keywordForDescriptorAtIndex:]`. - * @details Returns the keyword for the descriptor at the specified (one-based) position in the receiver. - Parameter index: The one-based descriptor list position of the descriptor to get the keyword for. - Returns: The keyword (a four-character code) for the descriptor at the one-based location specified by 'index', or 0 if an error occurs. * @param index Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ unsigned int keyword_for_descriptor_at_index(std::int64_t index) const; /** * @brief Calls `+[NSAppleEventDescriptor listDescriptor]`. - * @details Creates and initializes an empty list descriptor. A list descriptor is a descriptor whose data consists of one or more descriptors. You can add items to the list by calling '-insertDescriptor:atIndex:' or remove them with '-removeDescriptorAtIndex:'. Invoking this method is equivalent to allocating an instance of 'NSAppleEventDescriptor' and invoking '-initListDescriptor'. * @return The converted Objective-C result. */ static AppleEventDescriptor list_descriptor(); /** * @brief Calls `+[NSAppleEventDescriptor nullDescriptor]`. - * @details Creates and initializes a descriptor with no parameter or attribute values set. You don't typically call this method, as most 'NSAppleEventDescriptor' instance methods can't be safely called on the returned empty descriptor. * @return The converted Objective-C result. */ static AppleEventDescriptor null_descriptor(); /** * @brief Calls `-[NSAppleEventDescriptor paramDescriptorForKeyword:]`. - * @details Returns a descriptor for the receiver's Apple event parameter identified by the specified keyword. - Parameter keyword: A keyword (a four-character code) that identifies the parameter descriptor to obtain. - Returns: A descriptor for the specified keyword, or 'nil' if an error occurs. The receiver must be an Apple event. * @param keyword Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor param_descriptor_for_keyword(unsigned int keyword) const; /** * @brief Calls `+[NSAppleEventDescriptor recordDescriptor]`. - * @details Creates and initializes a descriptor for an Apple event record whose data has yet to be set. An Apple event record is a descriptor whose data is a set of descriptors keyed by four-character codes. You can add information to the descriptor with methods such as '-setAttributeDescriptor:forKeyword:', '-setDescriptor:forKeyword:', and '-setParamDescriptor:forKeyword:'. Invoking this method is equivalent to allocating an instance of 'NSAppleEventDescriptor' and invoking '-initRecordDescriptor'. * @return The converted Objective-C result. */ static AppleEventDescriptor record_descriptor(); /** * @brief Calls `-[NSAppleEventDescriptor removeDescriptorAtIndex:]`. - * @details Removes the descriptor at the specified (one-based) position in the receiving descriptor list. - Parameter index: The one-based position of the descriptor to remove. The receiver must be a list descriptor. The indices are one-based. Currently provides no indication if an error occurs. * @param index Argument converted to the Objective-C parameter of the same role. */ void remove_descriptor_at_index(std::int64_t index) const; /** * @brief Calls `-[NSAppleEventDescriptor removeDescriptorWithKeyword:]`. - * @details Removes the receiver's descriptor identified by the specified keyword. - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to remove. The receiver must be an Apple event or Apple event record. Currently provides no indication if an error occurs. * @param keyword Argument converted to the Objective-C parameter of the same role. */ void remove_descriptor_with_keyword(unsigned int keyword) const; /** * @brief Calls `-[NSAppleEventDescriptor removeParamDescriptorWithKeyword:]`. - * @details Removes the receiver's parameter descriptor identified by the specified keyword. - Parameter keyword: A keyword (a four-character code) that identifies the parameter descriptor to remove. The receiver must be an Apple event or Apple event record, both of which can contain parameters. Currently provides no indication if an error occurs. * @param keyword Argument converted to the Objective-C parameter of the same role. */ void remove_param_descriptor_with_keyword(unsigned int keyword) const; /** * @brief Calls `-[NSAppleEventDescriptor sendEventWithOptions:timeout:error:]`. - * @details Sends an Apple event. * @param send_options Argument converted to the Objective-C parameter of the same role. * @param timeout_in_seconds Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -258,124 +228,104 @@ namespace cocoon AppleEventDescriptor send_event_with_options(AppleEventSendOptions send_options, double timeout_in_seconds) const; /** * @brief Calls `-[NSAppleEventDescriptor setAttributeDescriptor:forKeyword:]`. - * @details Adds a descriptor to the receiver as an attribute identified by the specified keyword. - Parameters: - descriptor: The attribute descriptor to add to the receiver. - keyword: A keyword (a four-character code) that identifies the attribute descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced. The receiver must be an Apple event. Currently provides no indication if an error occurs. * @param descriptor Argument converted to the Objective-C parameter of the same role. * @param keyword Argument converted to the Objective-C parameter of the same role. */ void set_attribute_descriptor(const AppleEventDescriptor& descriptor, unsigned int keyword) const; /** * @brief Calls `-[NSAppleEventDescriptor setDescriptor:forKeyword:]`. - * @details Adds a descriptor, identified by a keyword, to the receiver. - Parameters: - descriptor: The descriptor to add to the receiver. - keyword: A keyword (a four-character code) that identifies the descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced. The receiver must be an Apple event or Apple event record. Currently provides no indication if an error occurs. * @param descriptor Argument converted to the Objective-C parameter of the same role. * @param keyword Argument converted to the Objective-C parameter of the same role. */ void set_descriptor(const AppleEventDescriptor& descriptor, unsigned int keyword) const; /** * @brief Calls `-[NSAppleEventDescriptor setParamDescriptor:forKeyword:]`. - * @details Adds a descriptor to the receiver as an Apple event parameter identified by the specified keyword. - Parameters: - descriptor: The parameter descriptor to add to the receiver. - keyword: A keyword (a four-character code) that identifies the parameter descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced. The receiver must be an Apple event or Apple event record, both of which can contain parameters. * @param descriptor Argument converted to the Objective-C parameter of the same role. * @param keyword Argument converted to the Objective-C parameter of the same role. */ void set_param_descriptor(const AppleEventDescriptor& descriptor, unsigned int keyword) const; /** * @brief Returns the `aeDesc` property of `NSAppleEventDescriptor`. - * @details The 'AEDesc' structure encapsulated by the receiver, if it has one. If the receiver has a valid 'AEDesc' structure, returns a pointer to it; otherwise returns 'nil'. * @return The converted Objective-C result. */ const AEDesc* ae_desc() const; /** * @brief Returns the `booleanValue` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as a Boolean value, coercing (to 'typeBoolean') if necessary. The contents of the descriptor, as a Boolean value, or 'false' if an error occurs. * @return The converted Objective-C result. */ std::uint8_t boolean_value() const; /** * @brief Returns the `data` property of `NSAppleEventDescriptor`. - * @details The receiver's data. An instance of 'NSData' containing the receiver's data, or 'nil' if an error occurs. * @return The converted Objective-C result. */ std::vector data() const; /** * @brief Returns the `dateValue` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as a date, coercing if necessary. * @return The converted Objective-C result. */ Date date_value() const; /** * @brief Returns the `descriptorType` property of `NSAppleEventDescriptor`. - * @details The descriptor type of the receiver. * @return The converted Objective-C result. */ unsigned int descriptor_type() const; /** * @brief Returns the `doubleValue` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as a double value, coercing (to 'typeIEEE64BitFloatingPoint') if necessary. * @return The converted Objective-C result. */ double double_value() const; /** * @brief Returns the `enumCodeValue` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as an enumeration type, coercing to 'typeEnumerated' if necessary. The contents of the descriptor, as an enumeration type, or 0 if an error occurs. * @return The converted Objective-C result. */ unsigned int enum_code_value() const; /** * @brief Returns the `eventClass` property of `NSAppleEventDescriptor`. - * @details The event class for the receiver. The event class (a four-character code) for the receiver, or 0 if an error occurs. The receiver must be an Apple event. An Apple event is identified by its event class and event ID, a pair of four-character codes stored as 32-bit integers. * @return The converted Objective-C result. */ unsigned int event_class() const; /** * @brief Returns the `eventID` property of `NSAppleEventDescriptor`. - * @details The event ID for the receiver. The event ID (a four-character code) for the receiver, or 0 if an error occurs. The receiver must be an Apple event. * @return The converted Objective-C result. */ unsigned int event_id() const; /** * @brief Returns the `fileURLValue` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as a file URL, coercing if necessary. * @return The converted Objective-C result. */ URL file_url_value() const; /** * @brief Returns the `int32Value` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as an integer, coercing (to 'typeSInt32') if necessary. The contents of the descriptor, as an integer value, or 0 if an error occurs. * @return The converted Objective-C result. */ int int32_value() const; /** * @brief Returns the `isRecordDescriptor` property of `NSAppleEventDescriptor`. - * @details Returns whether or not the receiver is a record-like descriptor. Record-like descriptors function as records, but may have a 'descriptorType' other than 'typeAERecord', such as 'typeObjectSpecifier'. * @return The converted Objective-C result. */ bool is_record_descriptor() const; /** * @brief Returns the `numberOfItems` property of `NSAppleEventDescriptor`. - * @details The number of descriptors in the receiver's descriptor list. The number of descriptors in the receiver's descriptor list (possibly 0); returns 0 if an error occurs. * @return The converted Objective-C result. */ std::int64_t number_of_items() const; /** * @brief Returns the `returnID` property of `NSAppleEventDescriptor`. - * @details The receiver's return ID (the ID for a reply Apple event). The receiver's return ID (an integer value), or 0 if an error occurs. The receiver must be an Apple event. * @return The converted Objective-C result. */ std::int16_t return_id() const; /** * @brief Returns the `stringValue` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as a Unicode text string, coercing to 'typeUnicodeText' if necessary. The contents of the descriptor, as a string, or 'nil' if an error occurs. * @return The converted Objective-C result. */ std::string string_value() const; /** * @brief Returns the `transactionID` property of `NSAppleEventDescriptor`. - * @details The receiver's transaction ID, if any. The receiver's transaction ID (an integer value), or 0 if an error occurs. The receiver must be an Apple event. * @return The converted Objective-C result. */ int transaction_id() const; /** * @brief Returns the `typeCodeValue` property of `NSAppleEventDescriptor`. - * @details The contents of the receiver as a type, coercing to 'typeType' if necessary. The contents of the descriptor, as a type, or 0 if an error occurs. * @return The converted Objective-C result. */ unsigned int type_code_value() const; diff --git a/include/generated/apple_event_manager.h b/include/generated/apple_event_manager.h index b6844c0b..f1fea31d 100644 --- a/include/generated/apple_event_manager.h +++ b/include/generated/apple_event_manager.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSAppleEventManager` (Foundation). - * @details A mechanism for registering handler routines for specific types of Apple events and dispatching events to those handlers. Cocoa provides built-in scriptability support that uses scriptability information supplied by an application to automatically convert Apple events into script command objects that perform the desired operation. However, some applications may want to perform more basic Apple event handling, in which an application registers handlers for the Apple events it can process, then calls on the Apple Event Manager to dispatch received Apple events to the appropriate handler. 'NSAppleEventManager' supports these mechanisms by providing methods to register and remove handlers and to dispatch Apple events to the appropriate handler, if one exists. For related information, see [How Cocoa Applications Handle Apple Events](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_handle_AEs/SAppsHandleAEs.html\#//apple_ref/doc/uid/20001239) Each application has at most one instance of 'NSAppleEventManager'. To obtain a reference to it, you call the class method ''shared()'', which creates the instance if it doesn't already exist. For information about the Apple Event Manager, see \ and Apple Events Programming Guide. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,14 +43,12 @@ namespace cocoon explicit AppleEventManager(Adopt adopt); /** * @brief Calls `-[NSAppleEventManager appleEventForSuspensionID:]`. - * @details Given a nonzero suspension ID returned by an invocation of '-suspendCurrentAppleEvent', returns the descriptor for the event whose handling was suspended. The effects of mutating or retaining the returned descriptor are undefined, although it may be copied. This method may be invoked in any thread, not just the one in which the corresponding invocation of '-suspendCurrentAppleEvent' occurred. * @param suspension_id Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor apple_event_for_suspension_id(const AppleEventManagerSuspensionID& suspension_id) const; /** * @brief Calls `-[NSAppleEventManager dispatchRawAppleEvent:withRawReply:handlerRefCon:]`. - * @details Causes the Apple event specified by 'theAppleEvent' to be dispatched to the appropriate Apple event handler, if one has been registered by calling '-setEventHandler:andSelector:forEventClass:andEventID:'. The 'theReply' parameter always specifies a reply Apple event, never 'nil'. However, the handler should not fill out the reply if the descriptor type for the reply event is 'typeNull', indicating the sender does not want a reply. The 'handlerRefcon' parameter provides 4 bytes of data to the handler; a common use for this parameter is to pass a pointer to additional data. This method is primarily intended for Cocoa's internal use. Note that dispatching an event means routing an event to an appropriate handler in the current application. You cannot use this method to send events to other applications. * @param the_apple_event Argument converted to the Objective-C parameter of the same role. * @param the_reply Argument converted to the Objective-C parameter of the same role. * @param handler_ref_con Argument converted to the Objective-C parameter of the same role. @@ -60,33 +57,28 @@ namespace cocoon std::int16_t dispatch_raw_apple_event(const AEDesc* the_apple_event, AEDesc* the_reply, void* handler_ref_con) const; /** * @brief Calls `-[NSAppleEventManager removeEventHandlerForEventClass:andEventID:]`. - * @details If an Apple event handler has been registered for the event specified by 'eventClass' and 'eventID', removes it. Otherwise does nothing. * @param event_class Argument converted to the Objective-C parameter of the same role. * @param event_id Argument converted to the Objective-C parameter of the same role. */ void remove_event_handler_for_event_class(unsigned int event_class, unsigned int event_id) const; /** * @brief Calls `-[NSAppleEventManager replyAppleEventForSuspensionID:]`. - * @details Given a nonzero suspension ID returned by an invocation of '-suspendCurrentAppleEvent', returns the corresponding reply event descriptor. This descriptor, including any mutations, will be returned to the sender of the suspended event when handling of the event is resumed, if the sender has requested a reply. The effects of retaining the descriptor are undefined; it may be copied, but mutations of the copy will not be returned to the sender of the suspended event. This method may be invoked in any thread, not just the one in which the corresponding invocation of '-suspendCurrentAppleEvent' occurred. * @param suspension_id Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor reply_apple_event_for_suspension_id(const AppleEventManagerSuspensionID& suspension_id) const; /** * @brief Calls `-[NSAppleEventManager resumeWithSuspensionID:]`. - * @details Given a nonzero suspension ID returned by an invocation of '-suspendCurrentAppleEvent', signal that handling of the suspended event may now continue. This may result in the immediate sending of the reply event to the sender of the suspended event, if the sender has requested a reply. If the suspension ID has been used in a previous invocation of '-setCurrentAppleEventAndReplyEventWithSuspensionID:' the effects of that invocation will be completely undone. Subsequent invocations of other 'NSAppleEventManager' methods using the same suspension ID are invalid. This method may be invoked in any thread, not just the one in which the corresponding invocation of '-suspendCurrentAppleEvent' occurred. * @param suspension_id Argument converted to the Objective-C parameter of the same role. */ void resume_with_suspension_id(const AppleEventManagerSuspensionID& suspension_id) const; /** * @brief Calls `-[NSAppleEventManager setCurrentAppleEventAndReplyEventWithSuspensionID:]`. - * @details Given a nonzero suspension ID returned by an invocation of '-suspendCurrentAppleEvent', sets the values that will be returned by subsequent invocations of 'currentAppleEvent' and 'currentReplyAppleEvent' to be the event whose handling was suspended and its corresponding reply event, respectively. Redundant invocations of this method will be ignored. * @param suspension_id Argument converted to the Objective-C parameter of the same role. */ void set_current_apple_event_and_reply_event_with_suspension_id(const AppleEventManagerSuspensionID& suspension_id) const; /** * @brief Calls `-[NSAppleEventManager setEventHandler:andSelector:forEventClass:andEventID:]`. - * @details Registers the Apple event handler specified by 'handler' for the event specified by 'eventClass' and 'eventID'. If an event handler is already registered for the specified event class and event ID, removes it. The signature for 'handler' should match the following: '''objc - (void)handleAppleEvent:(NSAppleEventDescriptor )event withReplyEvent:(NSAppleEventDescriptor )replyEvent; ''' When it is invoked, the value of the first parameter will be the event to be handled. The value of the second parameter will be the reply event to fill in. A reply event object will always be passed in (replyEvent will never be nil), but it should not be touched if the event sender has not requested a reply, which is indicated by '[replyEvent descriptorType]==typeNull'. * @param handler Argument converted to the Objective-C parameter of the same role. * @param handle_event_selector Argument converted to the Objective-C parameter of the same role. * @param event_class Argument converted to the Objective-C parameter of the same role. @@ -95,25 +87,21 @@ namespace cocoon void set_event_handler(const Object& handler, const std::string& handle_event_selector, unsigned int event_class, unsigned int event_id) const; /** * @brief Calls `+[NSAppleEventManager sharedAppleEventManager]`. - * @details Returns the single instance of 'NSAppleEventManager', creating it first if it doesn't exist. * @return The converted Objective-C result. */ static AppleEventManager shared_apple_event_manager(); /** * @brief Calls `-[NSAppleEventManager suspendCurrentAppleEvent]`. - * @details Suspends the handling of the current event and returns an ID that must be used to resume the handling of the event if an Apple event is being handled on the current thread. An Apple event is being handled on the current thread if 'currentAppleEvent' does not return 'nil'. Returns zero otherwise. The suspended event is no longer the current event after this method returns. * @return The converted Objective-C result. */ AppleEventManagerSuspensionID suspend_current_apple_event() const; /** * @brief Returns the `currentAppleEvent` property of `NSAppleEventManager`. - * @details Returns the descriptor for 'currentAppleEvent' if an Apple event is being handled on the current thread. An Apple event is being handled on the current thread if a handler that was registered with '-setEventHandler:andSelector:forEventClass:andEventID:' is being messaged at this instant or '-setCurrentAppleEventAndReplyEventWithSuspensionID:' has just been invoked. Returns 'nil' otherwise. The effects of mutating or retaining the returned descriptor are undefined, although it may be copied. * @return The converted Objective-C result. */ AppleEventDescriptor current_apple_event() const; /** * @brief Returns the `currentReplyAppleEvent` property of `NSAppleEventManager`. - * @details Returns the corresponding reply event descriptor if an Apple event is being handled on the current thread. An Apple event is being handled on the current thread if 'currentAppleEvent' does not return 'nil'. Returns 'nil' otherwise. This descriptor, including any mutations, will be returned to the sender of the current event when all handling of the event has been completed, if the sender has requested a reply. The effects of retaining the descriptor are undefined; it may be copied, but mutations of the copy are not returned to the sender of the current event. * @return The converted Objective-C result. */ AppleEventDescriptor current_reply_apple_event() const; diff --git a/include/generated/apple_script.h b/include/generated/apple_script.h index 90913c65..92a5b6d7 100644 --- a/include/generated/apple_script.h +++ b/include/generated/apple_script.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSAppleScript` (Foundation). - * @details An object that provides the ability to load, compile, and execute scripts. This class provides applications with the ability to - load a script from a URL or from a text string - compile or execute a script or an individual Apple event - obtain an 'NSAppleEventDescriptor' containing the reply from an executed script or event - obtain an attributed string for a compiled script, suitable for display in a script editor - obtain various kinds of information about any errors that may occur > Important: > 'NSAppleScript' provides the ''executeAppleEvent(:error:)'' method so that you can send an Apple event to invoke a handler in a script. (In an AppleScript script, a handler is the equivalent of a function.) However, you cannot use this method to send Apple events to other applications. When you create an instance of 'NSAppleScript' object, you can use a URL to specify a script that can be in either text or compiled form, or you can supply the script as a string. Should an error occur when compiling or executing the script, several of the methods return a dictionary containing error information. The keys for obtaining error information, such as ''errorMessage'', are described in the Constants section. See also NSAppleScript Additions Reference in the Application Kit framework, which defines a method that returns the syntax-highlighted source code for a script. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -40,21 +39,18 @@ namespace cocoon explicit AppleScript(Adopt adopt); /** * @brief Calls `-[NSAppleScript compileAndReturnError:]`. - * @details Compiles the receiver, if it is not already compiled. - Parameter errorInfo: On return, if an error occurs, a pointer to an error information dictionary. - Returns: 'YES' for success or if the script was already compiled, 'NO' otherwise. * @param error_info Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool compile_and_return_error(std::map& error_info) const; /** * @brief Calls `-[NSAppleScript executeAndReturnError:]`. - * @details Executes the receiver, compiling it first if it is not already compiled. - Parameter errorInfo: On return, if an error occurs, a pointer to an error information dictionary. - Returns: The result of executing the event, or 'nil' if an error occurs. Any changes to property values caused by executing the script do not persist. * @param error_info Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AppleEventDescriptor execute_and_return_error(std::map& error_info) const; /** * @brief Calls `-[NSAppleScript executeAppleEvent:error:]`. - * @details Executes an Apple event in the context of the receiver, as a means of allowing the application to invoke a handler in the script. - Parameters: - event: The Apple event to execute. - errorInfo: On return, if an error occurs, a pointer to an error information dictionary. - Returns: The result of executing the event, or 'nil' if an error occurs. Compiles the receiver before executing it if it is not already compiled. > Important: You cannot use this method to send Apple events to other applications. * @param event Argument converted to the Objective-C parameter of the same role. * @param error_info Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -62,7 +58,6 @@ namespace cocoon AppleEventDescriptor execute_apple_event(const AppleEventDescriptor& event, std::map& error_info) const; /** * @brief Returns the `compiled` property of `NSAppleScript`. - * @details A Boolean value that indicates whether the receiver's script has been compiled. * @return The converted Objective-C result. */ bool is_compiled() const; @@ -73,7 +68,6 @@ namespace cocoon AttributedString rich_text_source() const; /** * @brief Returns the `source` property of `NSAppleScript`. - * @details The script source for the receiver. It is possible for an 'NSAppleScript' that has been instantiated with '-initWithContentsOfURL:error:' to be a script for which the source code is not available but is nonetheless executable. * @return The converted Objective-C result. */ std::string source() const; diff --git a/include/generated/archiver.h b/include/generated/archiver.h index 01010e9d..1d933aed 100644 --- a/include/generated/archiver.h +++ b/include/generated/archiver.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSArchiver` (Foundation). - * @details A coder that stores an object's data to an archive. ''NSArchiver'', a concrete subclass of ''NSCoder'', provides a way to encode objects into an architecture-independent format that can be stored in a file. When you archive a graph of objects, the class information and instance variables for each object are written to the archive. The companion class ''NSUnarchiver'' decodes the data in an archive and creates a graph of objects equivalent to the original set. ''NSArchiver'' stores the archive data in a mutable data object (''NSMutableData''). After encoding the objects, you can have the ''NSArchiver'' object write this mutable data object immediately to a file, or you can retrieve the mutable data object for some other use. In macOS 10.2 and later, ''NSArchiver'' and ''NSUnarchiver'' have been replaced by ''NSKeyedArchiver'' and ''NSKeyedUnarchiver'' respectively—see [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html\#//apple_ref/doc/uid/10000047i). \@DeprecationSummary { Use ''NSKeyedArchiver'' instead. } + * @details Archiving: Writing * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Coder. * @@ -45,7 +45,6 @@ namespace cocoon using Coder::encode_root_object; /** * @brief Calls `+[NSArchiver archiveRootObject:toFile:]`. - * @details Archives an object graph rooted at a given object by encoding it into a data object then atomically writing the resulting data object to a file at a given path. This convenience method invokes ''NSArchiver/archivedDataWithRootObject:'' to get the encoded data, and then sends that data object the message ''NSData/writeToFile:atomically:'', using 'path' for the first argument and 'YES' for the second. The archived data should be retrieved from the archive by an ''NSUnarchiver'' object. - Parameters: - rootObject: The root object of the object graph to archive. - path: The location of the file into which to write the archive. - Returns: 'YES' if the archive was written successfully, otherwise 'NO'. * @param root_object Argument converted to the Objective-C parameter of the same role. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -53,47 +52,40 @@ namespace cocoon static bool archive_root_object(const Object& root_object, const std::string& path); /** * @brief Calls `+[NSArchiver archivedDataWithRootObject:]`. - * @details Returns a data object that contains the encoded form of the object graph formed by the given root object. This method invokes ''NSArchiver/initForWritingWithMutableData:'' and ''NSArchiver/encodeRootObject:'' to create a temporary archiver that encodes the object graph. - Parameter rootObject: The root object of the object graph to archive. - Returns: A data object containing the encoded form of the object graph whose root object is 'rootObject'. * @param root_object Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector archived_data_with_root_object(const Object& root_object); /** * @brief Calls `-[NSArchiver classNameEncodedForTrueClassName:]`. - * @details Returns the name under which a given class was encoded. - Parameter trueName: The real name of an encoded class. - Returns: The name of the class used to archive instances of the class 'trueName'. * @param true_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string class_name_encoded_for_true_class_name(const std::string& true_name) const; /** * @brief Calls `-[NSArchiver encodeClassName:intoClassName:]`. - * @details Encodes a given class under a given name. Any subsequently encountered objects of class 'trueName' are archived as instances of class 'inArchiveName'. It is safest not to invoke this method during the archiving process (that is, within an ''NSCoding/encode(with:)'' method). Instead, invoke it before ''encodeRootObject:''. - Parameters: - trueName: The real name of a class in the object graph being archived. - inArchiveName: The name of the class to use in the archive in place of 'trueName'. * @param true_name Argument converted to the Objective-C parameter of the same role. * @param in_archive_name Argument converted to the Objective-C parameter of the same role. */ void encode_class_name(const std::string& true_name, const std::string& in_archive_name) const; /** * @brief Calls `-[NSArchiver encodeConditionalObject:]`. - * @details Encodes an object only if it is referenced by another object in the archive. This method overrides the superclass implementation to allow 'object' to be encoded only if it is also encoded unconditionally by another object in the object graph. Conditional encoding lets you encode one part of a graph detached from the rest. This method should be invoked only from within an ''NSCoding/encode(with:)'' method. If 'object' is 'nil', the 'NSArchiver' object encodes it unconditionally as 'nil'. This method raises an 'NSInvalidArgumentException' if no root object has been encoded. - Parameter object: The object to archive. * @param object Argument converted to the Objective-C parameter of the same role. */ void encode_conditional_object(const Object& object) const; /** * @brief Calls `-[NSArchiver encodeRootObject:]`. - * @details Encodes a given root object, along with all of the objects it's connected to. If any object is encountered more than once while traversing the graph, it is encoded only once, but the multiple references to it are stored. This message must not be sent more than once to a given 'NSArchiver' object; an 'NSInvalidArgumentException' is raised if a root object has already been encoded. If you need to encode multiple object graphs, don't attempt to reuse an 'NSArchiver' instance; instead, create a new one for each graph. - Parameter rootObject: The root object of the object graph to archive. * @param root_object Argument converted to the Objective-C parameter of the same role. */ void encode_root_object(const Object& root_object) const; /** * @brief Calls `-[NSArchiver replaceObject:withObject:]`. - * @details Replaces one object with another during encoding. Causes the receiver to treat subsequent requests to encode 'object' as though they were requests to encode 'newObject' instead. Both 'object' and 'newObject' must be valid objects. - Parameters: - object: An object in the object graph being archived. - newObject: The object with which to replace 'object' in the archive. * @param object Argument converted to the Objective-C parameter of the same role. * @param new_object Argument converted to the Objective-C parameter of the same role. */ void replace_object(const Object& object, const Object& new_object) const; /** * @brief Returns the `archiverData` property of `NSArchiver`. - * @details The receiver's archive data. The returned data object is the same one specified as the argument to ''NSArchiver/init(forWritingWith:)''. It contains whatever data has been encoded thus far by invocations of the various encoding methods. It is safest not to invoke this method until after ''NSArchiver/encodeRootObject(:)'' has returned. In other words, although it is possible for a class to invoke this method from within its ''NSCoding/encode(with:)'' method, that method must not alter the data. * @return The converted Objective-C result. */ std::vector archiver_data() const; diff --git a/include/generated/assertion_handler.h b/include/generated/assertion_handler.h index 7a1e4f28..30f50bb6 100644 --- a/include/generated/assertion_handler.h +++ b/include/generated/assertion_handler.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSAssertionHandler` (Foundation). - * @details An object that logs an assertion to the console. 'NSAssertionHandler' objects are automatically created to handle false assertions. Assertion macros, such as 'NSAssert' and 'NSCAssert', are used to evaluate a condition, and if the condition evaluates to false, the macros pass a string to an 'NSAssertionHandler' object describing the failure. Each thread has its own 'NSAssertionHandler' object. When invoked, an assertion handler prints an error message that includes the method and class (or function) containing the assertion and raises an 'NSInternalInconsistencyException'. You create assertions only using the assertion macros—you rarely need to invoke 'NSAssertionHandler' methods directly. The macros for use inside methods and functions send ''handleFailureInMethod:object:file:lineNumber:description:'' and ''handleFailureInFunction:file:lineNumber:description:'' messages respectively to the current assertion handler. The assertion handler for the current thread is obtained using the ''current'' class method. See \ if you need to customize the behavior of ''NSAssertionHandler''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -32,7 +31,6 @@ namespace cocoon explicit AssertionHandler(Adopt adopt); /** * @brief Returns the `currentHandler` property of `NSAssertionHandler`. - * @details Returns the 'NSAssertionHandler' object associated with the current thread. If no assertion handler is associated with the current thread, this method creates one and assigns it to the thread. * @return The converted Objective-C result. */ static AssertionHandler current_handler(); diff --git a/include/generated/attributed_string.h b/include/generated/attributed_string.h index 1148e6c5..9b026ea0 100644 --- a/include/generated/attributed_string.h +++ b/include/generated/attributed_string.h @@ -21,7 +21,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSAttributedString` (Foundation). - * @details A string of text that manages data, layout, and stylistic information for ranges of characters to support rendering. ''NSAttributedString'' is a type you use to manage strings of stylized Unicode text. In addition to text, an attributed string contains key-value pairs known as attributes that specify additional information to apply to ranges of characters within the string. Attributed strings support many different kinds of attributes, including: - Rendering attributes that specify font, color, kern, ligature, and other details - Attributes for attachments and adaptive image glyphs - Semantic attributes such as link URLs or tool-tip information - Language attributes to support automatic gender agreement and text layout - Accessibility attributes that provide information for assistive technologies - Attributes that summarize details of the Markdown import process - Custom attributes you define for your app Use attributed strings anywhere you need styled text, or when you need to associate additional information with your text. Because ''NSAttributedString'' is an immutable type, you specify all of the text and attributes for it at creation time and can't change them later. You can create attributed strings directly from a string of characters and a dictionary of attributes. You can also create attributed strings from the contents of a file, including files that contain RTF, RTFD, HTML, Markdown, or other file formats. If you need to modify the contents of an attributed string later, use the ''NSMutableAttributedString'' type instead. If you create an ''NSAttributedString'' without any font information, the string's default font is Helvetica 12-point, which might differ from the default system font for the platform. To change the font, specify a font attribute at creation time. \#\#\# Persistence Be aware of how you persist attributed strings to and from the disk. RTF and RTFD are the preferred format for attributed strings because they offer the best fidelity for reading and writing attribute data. The RTF formats support a large number of standard attributes, and Apple extends the formats to support many Apple-specific attributes. If you define custom attributes for ranges of characters, store them separately alongside the RTF file for your text. If you work extensively with HTML content, validate the results and performance of import and export operations during testing. WebKit handles the conversion between HTML markup and attributed strings. If an HTML file contains tags or constructs that attributed strings don't support, the import process ignores them and imports what it can. When you create an attributed string from Markdown, the system adds presentation intent attributes with information about the original Markdown content. The system doesn't add style attributes to match the Markdown elements, but the system applies default style information when it renders a string with intent attributes. To change the rendering behavior of your Markdown content, remove the intent attributes and add the style attributes you prefer. > Important: > When reading or writing attributed strings, choose methods that return or throw an error, and check any errors you receive. Handling errors is the best way to detect issues with the import or export process and take corrective action. The methods for reading and writing common file formats also support document attributes. Document attributes aren't part of the attributed string itself, but accompany the text when you save it to a file. When you read a file, the system returns any document attributes that it finds. Similarly, when you write an attributed string to a file, you can specify the attributes to include. For more information about document attributes, see ''DocumentAttributeKey'' and ''DocumentReadingOptionKey''. \#\#\# System framework interoperability \ and \ use attributed strings extensively during the layout and rendering processes. These technologies use the string's text and rendering-related attributes to calculate the text metrics needed during layout. Similarly, these technologies apply those same attributes during rendering to give the text its styled appearance. The technologies use only attributes that directly affect the appearance of the text, and ignore most other attributes. For some attributes, the text system adds attributes during rendering as needed. For example, the text system provides default style attributes for text with the ''Key/link'' attribute. \ and \ also support attributed strings in several ways. Some views and controls in these frameworks have APIs that accept attributed strings, and render the string with its style information. The frameworks also add methods to the ''NSAttributedString'' class that let you draw a styled string directly in one of your custom views. Because these methods use TextKit to draw the string, they recognize the same rendering-related attributes as that technology. The ''NSAttributedString'' class and its Core Foundation counterpart, \, are toll-free bridged, which means you can use the two types interchangeably in your code without losing any text or attribute information. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -103,7 +102,6 @@ namespace cocoon std::vector rtf_from_range(const Range& range, const std::map& dict) const; /** * @brief Calls `-[NSAttributedString attribute:atIndex:effectiveRange:]`. - * @details Returns the value for an attribute with the specified name of the character at the specified index and, by reference, the range where the attribute applies. Raises an 'NSRangeException' if 'location' lies beyond the end of the receiver's characters. - Parameters: - attrName: The name of an attribute. - location: The index for which to return attributes. This value must not exceed the bounds of the receiver. - range: If non-'NULL', upon return contains a range over which the named attribute's value applies, or a range over which the attribute does not exist. The range isn't necessarily the maximum range covered by 'attrName', and its extent is implementation-dependent. If you need the maximum range, use 'attribute:atIndex:longestEffectiveRange:inRange:'. If you don't need this value, pass 'NULL'. - Returns: The value for the attribute named 'attrName' of the character at 'location', or 'nil' if there is no such attribute. * @param attr_name Argument converted to the Objective-C parameter of the same role. * @param location Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -112,7 +110,6 @@ namespace cocoon Object attribute(const std::string& attr_name, std::uint64_t location, Range* range) const; /** * @brief Calls `-[NSAttributedString attribute:atIndex:longestEffectiveRange:inRange:]`. - * @details Returns the value for the attribute with the specified name of the character at the specified index and, by reference, the range where the attribute applies. Raises an 'NSRangeException' if 'location' or any part of 'rangeLimit' lies beyond the end of the receiver's characters. If you don't need the longest effective range, it's far more efficient to use 'attribute:atIndex:effectiveRange:' to retrieve the attribute value. - Parameters: - attrName: The name of an attribute. - location: The index at which to test for 'attrName'. - range: If non-'NULL', upon return contains the full range over which the value of the named attribute is the same as that at 'location', clipped to 'rangeLimit', or the full range over which the attribute does not exist. If you don't need this value, pass 'NULL'. - rangeLimit: The range over which to search for continuous presence of 'attrName'. This value must not exceed the bounds of the receiver. - Returns: The value for the attribute named 'attrName' of the character at 'location', or 'nil' if there is no such attribute. * @param attr_name Argument converted to the Objective-C parameter of the same role. * @param location Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -128,14 +125,12 @@ namespace cocoon AttributedString attributed_string_by_inflecting_string() const; /** * @brief Calls `-[NSAttributedString attributedSubstringFromRange:]`. - * @details Returns an attributed string consisting of the characters and attributes within the specified range in the attributed string. Raises an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. This method treats the length of the string as a valid range value that returns an empty string. - Parameter range: The range from which to create a new attributed string. 'range' must lie within the bounds of the receiver. - Returns: An 'NSAttributedString' object consisting of the characters and attributes within 'range' in the receiver. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AttributedString attributed_substring_from_range(const Range& range) const; /** * @brief Calls `-[NSAttributedString attributesAtIndex:effectiveRange:]`. - * @details Returns the attributes for the character at the specified index. Raises an 'NSRangeException' if 'location' lies beyond the end of the receiver's characters. - Parameters: - location: The index for which to return attributes. This value must lie within the bounds of the receiver. - range: Upon return, the range over which the attributes and values are the same as those at 'location'. This range isn't necessarily the maximum range covered, and its extent is implementation-dependent. If you need the maximum range, use 'attributesAtIndex:longestEffectiveRange:inRange:'. If you don't need this value, pass 'NULL'. - Returns: The attributes for the character at 'location'. * @param location Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -143,7 +138,6 @@ namespace cocoon std::map attributes_at_index(std::uint64_t location, Range* range) const; /** * @brief Calls `-[NSAttributedString attributesAtIndex:longestEffectiveRange:inRange:]`. - * @details Returns the attributes for the character at the specified index and, by reference, the range where the attributes apply. Raises an 'NSRangeException' if 'location' or any part of 'rangeLimit' lies beyond the end of the receiver's characters. If you don't need the range information, it's far more efficient to use 'attributesAtIndex:effectiveRange:' to retrieve the attribute value. - Parameters: - location: The index for which to return attributes. This value must not exceed the bounds of the receiver. - range: If non-'NULL', upon return contains the maximum range over which the attributes and values are the same as those at 'location', clipped to 'rangeLimit'. - rangeLimit: The range over which to search for continuous presence of the attributes at 'location'. This value must not exceed the bounds of the receiver. * @param location Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. * @param range_limit Argument converted to the Objective-C parameter of the same role. @@ -216,7 +210,6 @@ namespace cocoon void draw_with_rect(const Rect& rect, StringDrawingOptions options, const StringDrawingContext& context) const; /** * @brief Calls `-[NSAttributedString enumerateAttribute:inRange:options:usingBlock:]`. - * @details Executes the specified block for each range of a particular attribute in the attributed string. If this method is called by an instance of 'NSMutableAttributedString', mutation (deletion, addition, or change) is allowed only if the mutation is within the range provided to the block. After a mutation, the enumeration continues with the range immediately following the processed range, adjusting for any change in length caused by the mutation. - Parameters: - attrName: The name of the attribute to enumerate. - enumerationRange: The range over which the attribute values are enumerated. - opts: The options used by the enumeration. - block: A block to apply to ranges of the specified attribute in the attributed string. * @param attr_name Argument converted to the Objective-C parameter of the same role. * @param enumeration_range Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. @@ -225,7 +218,6 @@ namespace cocoon void enumerate_attribute(const std::string& attr_name, const Range& enumeration_range, AttributedStringEnumerationOptions opts, std::function block) const; /** * @brief Calls `-[NSAttributedString enumerateAttributesInRange:options:usingBlock:]`. - * @details Executes the specified block for each range of attributes in the attributed string. If this method is called by an instance of 'NSMutableAttributedString', mutation (deletion, addition, or change) is allowed only if the mutation is within the range provided to the block. After a mutation, the enumeration continues with the range immediately following the processed range, adjusting for any change in length caused by the mutation. - Parameters: - enumerationRange: The range over which the attributes are enumerated. - opts: The options used by the enumeration. - block: The block to apply to ranges of attributes in the attributed string. * @param enumeration_range Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. @@ -246,7 +238,6 @@ namespace cocoon std::map font_attributes_in_range(const Range& range) const; /** * @brief Calls `-[NSAttributedString isEqualToAttributedString:]`. - * @details Returns a Boolean value that indicates whether the attributed string is equal to the specified string. This method performs a character-by-character comparison of the string and its attributes. The character and its attributes must be the same in both strings for the method to return 'YES'. - Parameter other: The attributed string with which to compare the receiver. - Returns: 'YES' if the text and attributes in the current string and 'other' are the same, otherwise 'NO'. * @param other Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -324,13 +315,11 @@ namespace cocoon bool contains_attachments() const; /** * @brief Returns the `length` property of `NSAttributedString`. - * @details The length of the attributed string. * @return The converted Objective-C result. */ std::uint64_t length() const; /** * @brief Returns the `string` property of `NSAttributedString`. - * @details The character contents of the receiver as a string. * @return The converted Objective-C result. */ std::string string() const; diff --git a/include/generated/attributed_string_markdown_parsing_options.h b/include/generated/attributed_string_markdown_parsing_options.h index c2b40f7e..f144e7c8 100644 --- a/include/generated/attributed_string_markdown_parsing_options.h +++ b/include/generated/attributed_string_markdown_parsing_options.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSAttributedStringMarkdownParsingOptions` (Foundation). - * @details Options that affect the parsing of Markdown content into an attributed string. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,61 +44,51 @@ namespace cocoon explicit AttributedStringMarkdownParsingOptions(Adopt adopt); /** * @brief Returns the `allowsExtendedAttributes` property of `NSAttributedStringMarkdownParsingOptions`. - * @details A Boolean value that indicates whether parsing allows extensions to Markdown that specify extended attributes. Defaults to 'NO' (only parse CommonMark syntax). * @return The converted Objective-C result. */ bool allows_extended_attributes() const; /** * @brief Sets the `allowsExtendedAttributes` property of `NSAttributedStringMarkdownParsingOptions`. - * @details A Boolean value that indicates whether parsing allows extensions to Markdown that specify extended attributes. Defaults to 'NO' (only parse CommonMark syntax). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_extended_attributes(bool value) const; /** * @brief Returns the `appliesSourcePositionAttributes` property of `NSAttributedStringMarkdownParsingOptions`. - * @details A Boolean value that indicates whether parsing applies attributes that indicate the position of attributed text in the original Markdown string. * @return The converted Objective-C result. */ bool applies_source_position_attributes() const; /** * @brief Sets the `appliesSourcePositionAttributes` property of `NSAttributedStringMarkdownParsingOptions`. - * @details A Boolean value that indicates whether parsing applies attributes that indicate the position of attributed text in the original Markdown string. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_applies_source_position_attributes(bool value) const; /** * @brief Returns the `failurePolicy` property of `NSAttributedStringMarkdownParsingOptions`. - * @details The policy for handling a parsing failure. The default is 'NSAttributedStringMarkdownParsingFailureReturnError'. * @return The converted Objective-C result. */ AttributedStringMarkdownParsingFailurePolicy failure_policy() const; /** * @brief Sets the `failurePolicy` property of `NSAttributedStringMarkdownParsingOptions`. - * @details The policy for handling a parsing failure. The default is 'NSAttributedStringMarkdownParsingFailureReturnError'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_failure_policy(AttributedStringMarkdownParsingFailurePolicy value) const; /** * @brief Returns the `interpretedSyntax` property of `NSAttributedStringMarkdownParsingOptions`. - * @details The syntax for interpreting a Markdown string. If your Markdown data uses syntax that this setting excludes, the parser still parses it and includes its text in the final result. However, the relevant text won't have attributes. * @return The converted Objective-C result. */ AttributedStringMarkdownInterpretedSyntax interpreted_syntax() const; /** * @brief Sets the `interpretedSyntax` property of `NSAttributedStringMarkdownParsingOptions`. - * @details The syntax for interpreting a Markdown string. If your Markdown data uses syntax that this setting excludes, the parser still parses it and includes its text in the final result. However, the relevant text won't have attributes. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_interpreted_syntax(AttributedStringMarkdownInterpretedSyntax value) const; /** * @brief Returns the `languageCode` property of `NSAttributedStringMarkdownParsingOptions`. - * @details The BCP-47 language code for this document. If not 'nil', the 'NSLanguageIdentifierAttributeName' attribute will be applied to any range in the returned string that doesn't otherwise specify a language attribute. The default is 'nil', which applies no attributes. * @return The converted Objective-C result. */ std::string language_code() const; /** * @brief Sets the `languageCode` property of `NSAttributedStringMarkdownParsingOptions`. - * @details The BCP-47 language code for this document. If not 'nil', the 'NSLanguageIdentifierAttributeName' attribute will be applied to any range in the returned string that doesn't otherwise specify a language attribute. The default is 'nil', which applies no attributes. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_language_code(const std::string& value) const; diff --git a/include/generated/attributed_string_markdown_source_position.h b/include/generated/attributed_string_markdown_source_position.h index 2c227676..41cf9b16 100644 --- a/include/generated/attributed_string_markdown_source_position.h +++ b/include/generated/attributed_string_markdown_source_position.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSAttributedStringMarkdownSourcePosition` (Foundation). - * @details The position of attributed string text in its original Markdown source string. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -41,32 +40,27 @@ namespace cocoon explicit AttributedStringMarkdownSourcePosition(Adopt adopt); /** * @brief Calls `-[NSAttributedStringMarkdownSourcePosition rangeInString:]`. - * @details Returns a range indicating the source portion within a Markdown string. Use this method to access the marked-up region of 'string' with an 'NSRange', rather than making manual calculations based on row and column values. - Parameter string: The Markdown source string that this source position object refers to. - Returns: A range that represents the source portion within a source Markdown string. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Range range_in_string(const std::string& string) const; /** * @brief Returns the `endColumn` property of `NSAttributedStringMarkdownSourcePosition`. - * @details The column where the text ends in the Markdown source. Uses 1-based counting. Columns represent UTF-8 indices; for multi-byte characters, the column indicates the first byte. * @return The converted Objective-C result. */ std::int64_t end_column() const; /** * @brief Returns the `endLine` property of `NSAttributedStringMarkdownSourcePosition`. - * @details The line where the text ends in the Markdown source. Uses 1-based counting. * @return The converted Objective-C result. */ std::int64_t end_line() const; /** * @brief Returns the `startColumn` property of `NSAttributedStringMarkdownSourcePosition`. - * @details The column where the text begins in the Markdown source. Uses 1-based counting. Columns represent UTF-8 indices; for multi-byte characters, the column indicates the first byte. * @return The converted Objective-C result. */ std::int64_t start_column() const; /** * @brief Returns the `startLine` property of `NSAttributedStringMarkdownSourcePosition`. - * @details The line where the text begins in the Markdown source. Uses 1-based counting. * @return The converted Objective-C result. */ std::int64_t start_line() const; diff --git a/include/generated/availability.h b/include/generated/availability.h index 9172e4b9..190a817d 100644 --- a/include/generated/availability.h +++ b/include/generated/availability.h @@ -1,11 +1,3 @@ #pragma once #include - -#if defined(COCOON_SDK_MAJOR) -#if COCOON_SDK_MAJOR >= 27 -#define COCOON_MACOS_27 -#endif -#elif defined(__MAC_OS_X_VERSION_MAX_ALLOWED) && __MAC_OS_X_VERSION_MAX_ALLOWED >= 270000 -#define COCOON_MACOS_27 -#endif diff --git a/include/generated/background_activity_scheduler.h b/include/generated/background_activity_scheduler.h index 196c8b03..b4bef73c 100644 --- a/include/generated/background_activity_scheduler.h +++ b/include/generated/background_activity_scheduler.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSBackgroundActivityScheduler` (Foundation). - * @details A task scheduler suitable for low priority operations that can run in the background. Use an ''NSBackgroundActivityScheduler'' object to schedule an arbitrary maintenance or background task. It's similar to an ''Timer'' object, in that it lets you schedule a repeating or non-repeating task. However, ''NSBackgroundActivityScheduler'' gives the system flexibility to determine the most efficient time to execute based on energy usage, thermal conditions, and CPU use. For example, use an ''NSBackgroundActivityScheduler'' object to schedule: - Automatic saves - Backups - Data maintenance - Periodic content fetches - Installation of updates - Activities occurring in intervals of 10 minutes or more - Any other deferrable task For information about performing non-deferrable tasks efficiently, see [Specify Nondeferrable Background Activities](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/SchedulingBackgroundActivity.html\#//apple_ref/doc/uid/TP40013929-CH32-SW10) in [Energy Efficiency Guide for Mac Apps](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/index.html\#//apple_ref/doc/uid/TP40013929). > Note: > The ''NSBackgroundActivityScheduler'' class interfaces with the XPC Activity API. However, your app doesn't need to be an XPC service in order to use ''NSBackgroundActivityScheduler''. \#\#\# Create a Scheduler To initialize a scheduler, call ''init(identifier:)'' for 'NSBackgroundActivityScheduler', and pass it a unique identifier string in reverse DNS notation ('nil' and zero-length strings are not allowed) that remains constant across launches of your application. \@TabNavigator { \@Tab("Swift") { '''swift let activity = NSBackgroundActivityScheduler(identifier: "com.example.MyApp.updatecheck") ''' } \@Tab("Objective-C") { '''objc NSBackgroundActivityScheduler activity = [[NSBackgroundActivityScheduler alloc] initWithIdentifier:\@"com.example.MyApp.updatecheck"]; ''' } } > Note: > The system uses this unique identifier to track the number of times the activity has run and to improve the heuristics for deciding when to run it again in the future. \#\#\# Configure Scheduler Properties Configure the scheduler with any of the following scheduling properties: - ''repeats''—If set to \, the activity is rescheduled at the specified interval after finishing. - ''interval''—For repeating schedulers, the average interval between invocations of the activity. For nonrepeating schedulers, 'interval' is the suggested interval of time between scheduling the activity and the invocation of the activity. - ''tolerance''—The amount of time before or after the nominal fire date when the activity should be invoked. The nominal fire date is calculated by using the interval combined with the previous fire date or the time when the activity is started. These two properties create a window in time, during which the activity may be scheduled. The system will more aggressively schedule the activity as it nears the end of the grace period after the nominal fire date. The default value is half the interval. - ''qualityOfService''—The default value is 'NSQualityOfServiceBackground'. If you upgrade the quality of service above this level, the system schedules the activity more aggressively. The default value is the recommended value for most activities. For information on quality of service, see [Prioritize Work at the Task Level](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/PrioritizeWorkAtTheTaskLevel.html\#//apple_ref/doc/uid/TP40013929-CH35) in [Energy Efficiency Guide for Mac Apps](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/index.html\#//apple_ref/doc/uid/TP40013929). The next three code examples demonstrate different scheduling scenarios. Scheduling an activity to fire in the next 10 minutes \@TabNavigator { \@Tab("Swift") { '''swift activity.tolerance = 10 60 ''' } \@Tab("Objective-C") { '''objc activity.tolerance = 10 60; ''' } } Scheduling an activity to fire between 15 and 45 minutes from now \@TabNavigator { \@Tab("Swift") { '''swift activity.interval = 30 60 activity.tolerance = 15 60 ''' } \@Tab("Objective-C") { '''objc activity.interval = 30 60; activity.tolerance = 15 60; ''' } } Scheduling an activity to fire once each hour \@TabNavigator { \@Tab("Swift") { '''swift activity.repeats = true activity.interval = 60 60 ''' } \@Tab("Objective-C") { '''objc activity.repeats = YES; activity.interval = 60 60; ''' } } \#\#\# Schedule Activity with scheduleWithBlock: When you're ready to schedule the activity, call 'scheduleWithBlock:' and provide a block of code to execute when the scheduler runs, as shown in the following example. The block will be called on a serial background queue appropriate for the level of quality of service specified. The system automatically uses the ''ProcessInfo/beginActivity(options:reason:)'' method (of ''ProcessInfo'') while invoking the block, choosing appropriate options based on the specified quality of service. When your block is called, it's passed a completion handler as an argument. Configure the block to invoke this handler, passing it a result of type ''Result'' to indicate whether the activity finished (''Result/finished'') or should be deferred (''Result/deferred'') and rescheduled for a later time. Failure to invoke the completion handler results in the activity not being rescheduled. For work that will be deferred and rescheduled, the block may optionally adjust scheduler properties, such as ''interval'' or ''tolerance'', before calling the completion handler. Scheduling background activity \@TabNavigator { \@Tab("Swift") { '''swift activity.scheduleWithBlock() { (completion: NSBackgroundActivityCompletionHandler) in // Perform the activity self.completion(NSBackgroundActivityResult.Finished) } ''' } \@Tab("Objective-C") { '''objc [activity scheduleWithBlock:^(NSBackgroundActivityCompletionHandler completion) { // Perform the activity self.completion(NSBackgroundActivityResultFinished); }]; ''' } } \#\#\# Detect Whether to Defer Activity It's conceivable that while a lengthy activity is running, conditions may change, resulting in the activity now requiring deferral. For example, perhaps the user has unplugged the Mac and it's now running on battery power. Your activity can call ''shouldDefer'' to determine whether this has occurred. A value of \ indicates that the block should finish what it's currently doing and invoke its completion handler with a value of ''Result/deferred''. See the following example. Detecting deferred background activity \@TabNavigator { \@Tab("Swift") { '''swift if activity.shouldDefer { // Wrap up processing and prepare to defer activity self.completion(NSBackgroundActivityResult.Deferred) } else { // Continue processing self.completion(NSBackgroundActivityResult.Finished) } ''' } \@Tab("Objective-C") { '''objc if ([activity shouldDefer]) { // Wrap up processing and prepare to defer activity self.completion(NSBackgroundActivityResultDeferred); } else { // Continue processing self.completion(NSBackgroundActivityResultFinished); }; ''' } } \#\#\# Stop Activity Call ''invalidate()'' to stop scheduling an activity, as shown in the following example. Stopping background activity \@TabNavigator { \@Tab("Swift") { '''swift activity.invalidate() ''' } \@Tab("Objective-C") { '''objc [activity invalidate]; ''' } } > Note: > When an activity is stopped, a block that's currently executing will still finish executing. + * @details This class provides a Cocoa-level interface to the XPC Activity API (see xpc/activity.h). It is used to schedule maintenance or background kinds of tasks. These activities are run by the OS at a time that best accommodates system-wide factors like energy, thermal conditions, and CPU usage. If you have activities that run at an interval measured in 10s of minutes or more, then use this class to schedule those activities. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,72 +48,72 @@ namespace cocoon explicit BackgroundActivityScheduler(Adopt adopt); /** * @brief Calls `-[NSBackgroundActivityScheduler invalidate]`. - * @details Prevents the background activity from being scheduled again. When 'invalidate' is used to stop an activity that is currently executing, the activity will still finish executing. + * @details Stop scheduling the activity. Any currently executing block will still complete. */ void invalidate() const; /** * @brief Calls `-[NSBackgroundActivityScheduler scheduleWithBlock:]`. - * @details Begins scheduling the background activity. - Parameters: - block: A block of code to execute when the scheduler runs. This block will be called on a serial background queue appropriate for the level of quality of service specified. See 'qualityOfService'. When your block is called, it's passed a completion handler as an argument. Configure the block to invoke this handler, passing it a result of type 'NSBackgroundActivityResult' to indicate whether the activity finished ('NSBackgroundActivityResultFinished') or should be deferred ('NSBackgroundActivityResultDeferred') and rescheduled for a later time. Failure to invoke the completion handler results in the activity not being rescheduled. For work that will be deferred and rescheduled, the block may optionally adjust scheduler properties, such as 'interval' or 'tolerance', before calling the completion handler. + * @details Begin scheduling the activity. All properties should be setup by this point. The block will be called on a serial background queue appropriate for the level of quality of service specified. The system will automatically use NSProcessInfo's -beginActivityWithOptions:reason: API while invoking the block, choosing options appropriate for the desired quality of service. When you are done with the work, be sure to invoke the completionHandler block given to you as an argument to your block. You can pass in a kind of NSBackgroundActivityResult to indicate if the work has been finished or if you are deferring the rest of the work (see -shouldDefer). If you fail to invoke the completionHandler then your activity will never be rescheduled. When invoking the completionHandler, the system will set the schedule the next invocation. If you want to adjust the properties of your scheduler (e.g., the interval or tolerance), do this before invoking the completion block. * @param block Argument converted to the Objective-C parameter of the same role. */ void schedule_with_block(std::function)> block) const; /** * @brief Returns the `identifier` property of `NSBackgroundActivityScheduler`. - * @details A unique reverse DNS notation string, such as 'com.example.MyApp.updatecheck', that identifies the activity. This string should remain constant for an activity across launches of your app because the system uses this unique identifier to track the number of times the activity has run and to improve the heuristics for deciding when to run it again in the future. 'nil' and zero-length strings are not allowed. + * @details The identifier this object was initialized with. * @return The converted Objective-C result. */ std::string identifier() const; /** * @brief Returns the `interval` property of `NSBackgroundActivityScheduler`. - * @details An integer providing a suggested interval between scheduling and invoking the activity. For repeating activities, the value of this property is also the suggested interval between invocations. + * @details If this activity is repeating, then this property describes the average interval of seconds between invocations of this activity. If the activity is not repeating, then this property is the suggested interval of time between scheduling the activity and the invocation of the activity. * @return The converted Objective-C result. */ double interval() const; /** * @brief Sets the `interval` property of `NSBackgroundActivityScheduler`. - * @details An integer providing a suggested interval between scheduling and invoking the activity. For repeating activities, the value of this property is also the suggested interval between invocations. + * @details If this activity is repeating, then this property describes the average interval of seconds between invocations of this activity. If the activity is not repeating, then this property is the suggested interval of time between scheduling the activity and the invocation of the activity. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_interval(double value) const; /** * @brief Returns the `qualityOfService` property of `NSBackgroundActivityScheduler`. - * @details A value of type 'NSQualityOfService', which controls how aggressively the system schedules the activity. The default value is 'NSQualityOfServiceBackground'. If you upgrade the quality of service above this level, the system schedules the activity more aggressively. The default value is the recommended value for most activities. + * @details Default value is NSQualityOfServiceBackground. If you upgrade the quality of service above this level, the system will more aggressively schedule this activity. The default value is the recommended value for most activities. * @return The converted Objective-C result. */ QualityOfService quality_of_service() const; /** * @brief Sets the `qualityOfService` property of `NSBackgroundActivityScheduler`. - * @details A value of type 'NSQualityOfService', which controls how aggressively the system schedules the activity. The default value is 'NSQualityOfServiceBackground'. If you upgrade the quality of service above this level, the system schedules the activity more aggressively. The default value is the recommended value for most activities. + * @details Default value is NSQualityOfServiceBackground. If you upgrade the quality of service above this level, the system will more aggressively schedule this activity. The default value is the recommended value for most activities. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_quality_of_service(QualityOfService value) const; /** * @brief Returns the `repeats` property of `NSBackgroundActivityScheduler`. - * @details A Boolean value indicating whether the activity should be rescheduled after it completes. The default value for this property is 'NO'. + * @details The default value is NO. If set to YES, then the activity will be rescheduled after finishing at the specified interval. * @return The converted Objective-C result. */ bool repeats() const; /** * @brief Sets the `repeats` property of `NSBackgroundActivityScheduler`. - * @details A Boolean value indicating whether the activity should be rescheduled after it completes. The default value for this property is 'NO'. + * @details The default value is NO. If set to YES, then the activity will be rescheduled after finishing at the specified interval. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_repeats(bool value) const; /** * @brief Returns the `shouldDefer` property of `NSBackgroundActivityScheduler`. - * @details A Boolean value indicating whether your app should stop performing background activity and resume at a more optimal time. Your app can check the 'shouldDefer' property while executing scheduled background activity. If this property contains a value of 'YES', system conditions have changed since the time the activity started and deferral is recommended. For example, perhaps the user unplugged the Mac and it's now running on battery power. In this case, your app should finish what it's currently doing, save its state, and invoke its completion handler with a value of 'NSBackgroundActivityResultDeferred'. The system will invoke your activity again at a more optimal time, and your app can restore its previous state and resume where it left off. + * @details You can call this method occasionally during execution of your activity to determine if system conditions have changed such that it is no longer a good time to run this activity. If the result of this method is YES, then you should wrap up current state. Once you are done saving your state, invoke the completionHandler block (the argument to your scheduled block) with the NSBackgroundActivityResultDeferred constant. The system will invoke your activity block again at a later, more appropriate time. At that point you can read your state and continue the work. * @return The converted Objective-C result. */ bool should_defer() const; /** * @brief Returns the `tolerance` property of `NSBackgroundActivityScheduler`. - * @details A value of type 'NSTimeInterval', which specifies a range of time during which the background activity may occur. A nominal fire date for scheduled background activity is calculated based on a combination of the 'interval' property value and the time the activity began or the last execution date. The 'tolerance' property specifies a grace period -- a range of time before and after the nominal fire date, during which the activity may be invoked. As the activity nears the end of its grace period, the system schedules the activity more aggressively. The default tolerance period is half the value of the 'interval' property. + * @details Specifies the number of seconds before or after the nominal fire date when the activity should be invoked. The nominal fire date is calculated by using the interval combined with the previous fire date or the time when the activity is started. These two properties create a window in time during which the activity may be scheduled. The system will more aggresively schedule the activity as it nears the end of the grace period after the nominal fire date. The default value is 1/2 the interval. * @return The converted Objective-C result. */ double tolerance() const; /** * @brief Sets the `tolerance` property of `NSBackgroundActivityScheduler`. - * @details A value of type 'NSTimeInterval', which specifies a range of time during which the background activity may occur. A nominal fire date for scheduled background activity is calculated based on a combination of the 'interval' property value and the time the activity began or the last execution date. The 'tolerance' property specifies a grace period -- a range of time before and after the nominal fire date, during which the activity may be invoked. As the activity nears the end of its grace period, the system schedules the activity more aggressively. The default tolerance period is half the value of the 'interval' property. + * @details Specifies the number of seconds before or after the nominal fire date when the activity should be invoked. The nominal fire date is calculated by using the interval combined with the previous fire date or the time when the activity is started. These two properties create a window in time during which the activity may be scheduled. The system will more aggresively schedule the activity as it nears the end of the grace period after the nominal fire date. The default value is 1/2 the interval. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tolerance(double value) const; diff --git a/include/generated/block_operation.h b/include/generated/block_operation.h index 937171fd..f05f8491 100644 --- a/include/generated/block_operation.h +++ b/include/generated/block_operation.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSBlockOperation` (Foundation). - * @details An operation that manages the concurrent execution of one or more blocks. The ''BlockOperation'' class is a concrete subclass of ''Operation'' that manages the concurrent execution of one or more blocks. You can use this object to execute several blocks at once without having to create separate operation objects for each. When executing more than one block, the operation itself is considered finished only when all blocks have finished executing. Blocks added to a block operation are dispatched with default priority to an appropriate work queue. The blocks themselves should not make any assumptions about the configuration of their execution environment. For more information about blocks, see [Blocks Programming Topics](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html\#//apple_ref/doc/uid/TP40007502). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Operation. * @@ -35,7 +34,6 @@ namespace cocoon explicit BlockOperation(Adopt adopt); /** * @brief Calls `-[NSBlockOperation addExecutionBlock:]`. - * @details Adds the specified block to the receiver's list of blocks to perform. The specified block should not make any assumptions about its execution environment. Calling this method while the receiver is executing or has already finished causes an 'NSInvalidArgumentException' exception to be thrown. - Parameter block: The block to add to the receiver's list. The block should take no parameters and have no return value. * @param block Argument converted to the Objective-C parameter of the same role. */ void add_execution_block(std::function block) const; diff --git a/include/generated/browser.h b/include/generated/browser.h index 1de0cf9f..e24c1a1f 100644 --- a/include/generated/browser.h +++ b/include/generated/browser.h @@ -10,7 +10,6 @@ namespace cocoon { class Cell; class Color; - class DraggingSession; class Event; class Image; class IndexPath; @@ -793,30 +792,6 @@ namespace cocoon { return Signal(handle(), "should_show_cell_expansion_for_row_column"); } -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `pasteboard_writer_for_row_column`; connect a callback with `pasteboard_writer_for_row_column().connect(...)`. - Signal pasteboard_writer_for_row_column() const - { - return Signal(handle(), "pasteboard_writer_for_row_column"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `dragging_session_will_begin_at_point_for_rows_with_indexes_column`; connect a callback with `dragging_session_will_begin_at_point_for_rows_with_indexes_column().connect(...)`. - Signal dragging_session_will_begin_at_point_for_rows_with_indexes_column() const - { - return Signal(handle(), "dragging_session_will_begin_at_point_for_rows_with_indexes_column"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `dragging_session_ended_at_point_operation`; connect a callback with `dragging_session_ended_at_point_operation().connect(...)`. - Signal dragging_session_ended_at_point_operation() const - { - return Signal(handle(), "dragging_session_ended_at_point_operation"); - } -#endif - /// @brief Signal for the delegate/data-source method behind `write_rows_with_indexes_in_column_to_pasteboard`; connect a callback with `write_rows_with_indexes_in_column_to_pasteboard().connect(...)`. Signal write_rows_with_indexes_in_column_to_pasteboard() const { diff --git a/include/generated/bundle.h b/include/generated/bundle.h index 4d30e0e2..38e07eb2 100644 --- a/include/generated/bundle.h +++ b/include/generated/bundle.h @@ -15,7 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSBundle` (Foundation). - * @details A representation of the code and resources stored in a bundle directory on disk. Apple uses bundles to represent apps, frameworks, plug-ins, and many other specific types of content. Bundles organize their contained resources into well-defined subdirectories, and bundle structures vary depending on the platform and the type of the bundle. By using a bundle object, you can access a bundle's resources without knowing the structure of the bundle. The bundle object provides a single interface for locating items, taking into account the bundle structure, user preferences, available localizations, and other relevant factors. Any executable can use a bundle object to locate resources, either inside an app's bundle or in a known bundle located elsewhere. You don't use a bundle object to locate files in a container directory or in other parts of the file system. The general pattern for using a bundle object is as follows: 1. Create a bundle object for the intended bundle directory. 2. Use the methods of the bundle object to locate or load the needed resource. 3. Use other system APIs to interact with the resource. Some types of frequently used resources can be located and opened without a bundle. For example, when loading images, you store images in asset catalogs and load them using the \ methods of \ or \. Similarly, for string resources, you use ''NSLocalizedString'' to load individual strings instead of loading the entire '.strings' file yourself. > Note: Unlike some other Foundation classes with corresponding Core Foundation names (such as ''NSString'' and \), ''Bundle'' objects cannot be cast to \ references. If you need functionality provided by \, you can still create a \ and use the \ API. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information. \#\#\# Finding and Opening a Bundle Before you can locate a resource, you must first specify which bundle contains it. The ''Bundle'' class has many constructors, but the one you use most often is ''main''. The main bundle represents the bundle directory that contains the currently executing code. So for an app, the main bundle object gives you access to the resources that shipped with your app. If your app interacts directly with plug-ins, frameworks, or other bundled content, you can use other methods of this class to create appropriate bundle objects. You can always create bundle objects from a known URL or path, but other methods make it easier to access bundles your app is already using. For example, if you link to a framework, you can use the ''init(for:)'' method to locate the framework bundle based on a class defined in that framework. \@TabNavigator { \@Tab("Swift") { '''swift // Get the app's main bundle let mainBundle = Bundle.main // Get the bundle containing the specified private class. let myBundle = Bundle(for: NSClassFromString("MyPrivateClass")!) ''' } \@Tab("Objective-C") { '''objc // Get the app's main bundle NSBundle main = [NSBundle mainBundle]; // Get the bundle containing the specified private class. NSBundle myBundle = [NSBundle bundleForClass:[MyPrivateClass class]]; ''' } } In Swift, use the ''bundle()'' macro to insert a bundle instance appropriate to the current execution context, whether an app, app extension, framework, or Swift package. \#\#\# Locating Resources in a Bundle You use ''Bundle'' objects to obtain the location of specific resources inside the bundle. When looking for resources, you provide the name of the resource and its type at a minimum. For resources in a specific subdirectory, you can also specify that directory. After locating the resource, the bundle routines return a path string or URL that you can use to open the file. Locating a single resource in a bundle '''objc NSBundle main = [NSBundle mainBundle]; NSString resourcePath = [main pathForResource:\@"Seagull" ofType:\@"jpg"]; ''' Bundle objects follow a specific search pattern when looking for resources on disk. Global resources—that is, resources not in a language-specific '.lproj' directory—are returned first, followed by region- and language-specific resources. This search pattern means that the bundle looks for resources in the following order: 1. Global (nonlocalized) resources 2. Region-specific localized resources (based on the user's region preferences) 3. Language-specific localized resources (based on the user's language preferences) 4. Development language resources (as specified by the [CFBundleDevelopmentRegion](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html\#//apple_ref/doc/uid/20001431-130430) key in the bundle's Info.plist file) Because global resources take precedence over language-specific resources, you should never include both a global and localized version of a given resource in your app. When a global version of a resource exists, language-specific versions are never returned. The reason for this precedence is performance. If localized resources were searched first, the bundle object might waste time searching for a nonexistent localized resource before returning the global resource. > Important: > Bundle objects always consider case when searching for resource files, even on file systems that support case-insensitive filenames. Always make sure that you specify filenames with case sensitivity in mind. When locating resource files, the bundle object automatically considers many standard filename modifiers when determining which file to return. Resources may be tagged for a specific device ('~iphone', '~ipad') or for a specific screen resolution ('\@2x', '\@3x'). Do not include these modifiers when specifying the name of the resource you want. The bundle object selects the file that is most appropriate for the underlying device. For more information, see [App Icons on iPhone, iPad and Apple Watch](https://developer.apple.com/library/archive/qa/qa1686/index.html\#//apple_ref/doc/uid/DTS40009882). \#\#\# Understanding Bundle Structures Bundle structures vary depending on the target platform and the type of bundle you are building. The ''Bundle'' class hides this underlying structure in most (but not all) cases. Many of the methods you use to load resources from a bundle automatically locate the appropriate starting directory and look for resources in known places. You can also use the methods and properties of this class to get the location of known bundle directories and to retrieve resources specifically from those directories. For information about the bundle structure of iOS and macOS apps, see [Bundle Programming Guide](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html\#//apple_ref/doc/uid/10000123i). For information about the structure of framework bundles, see [Framework Programming Guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Frameworks.html\#//apple_ref/doc/uid/10000183i). For information about the structure of macOS plug-ins, see [Code Loading Programming Topics](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingCode/LoadingCode.html\#//apple_ref/doc/uid/10000052i). + * @details Because NSBundle caches allocated instances, subclasses should be prepared to receive an already initialized object back from [super initWithPath:] * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -51,7 +51,6 @@ namespace cocoon explicit Bundle(Adopt adopt); /** * @brief Calls `-[NSBundle URLForAuxiliaryExecutable:]`. - * @details Returns the file URL of the executable with the specified name in the receiver's bundle. This method returns the appropriate path for modern application and framework bundles. This method may not return a URL for non-standard bundle formats or for some older bundle formats. \@param executableName The name of an executable file. \@return The file URL of the executable in the receiver's bundle. * @param executable_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -64,7 +63,6 @@ namespace cocoon URL url_for_image_resource(const std::string& name) const; /** * @brief Calls `-[NSBundle URLForResource:withExtension:]`. - * @details Returns the file URL for the resource identified by the specified name and file extension. \@param name The name of the resource file. If \@c nil, the method returns the first resource file it finds with the specified extension. \@param ext The extension of the resource file. If an empty string or \@c nil, the extension is assumed not to exist. \@return The file URL for the resource file or \@c nil if the file could not be located. * @param name Argument converted to the Objective-C parameter of the same role. * @param ext Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -72,7 +70,6 @@ namespace cocoon URL url_for_resource(const std::string& name, const std::string& ext) const; /** * @brief Calls `-[NSBundle URLForResource:withExtension:subdirectory:]`. - * @details Returns the file URL for the resource file identified by the specified name and extension and residing in a given bundle directory. \@param name The name of a resource file. If \@c nil, the method returns the first resource file it finds with the specified extension. \@param ext The filename extension of the file to locate. If an empty string or \@c nil, the extension is assumed not to exist. \@param subpath The name of the bundle subdirectory to search. \@return The file URL for the resource file or \@c nil if the file could not be located. * @param name Argument converted to the Objective-C parameter of the same role. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. @@ -81,7 +78,7 @@ namespace cocoon URL url_for_resource(const std::string& name, const std::string& ext, const std::string& subpath) const; /** * @brief Calls `+[NSBundle URLForResource:withExtension:subdirectory:inBundleWithURL:]`. - * @details Creates and returns a file URL for the resource with the specified name and extension in the specified bundle. \@param name The name of the resource file. If \@c nil, the method returns the first resource file it finds that matches the remaining criteria. \@param ext The filename extension of the file to locate. If an empty string or \@c nil, the extension is assumed not to exist. \@param subpath The name of the bundle subdirectory to search. \@param bundleURL The file URL of the bundle to search. \@return The file URL for the resource file or \@c nil if the file could not be located. + * @details Methods for locating bundle resources. Instance methods locate resources in the bundle indicated by the receiver; class methods take an argument pointing to a bundle on disk. In the class methods, bundleURL is a URL pointing to the location of a bundle on disk, and may not be nil; bundlePath is the path equivalent of bundleURL, an absolute path pointing to the location of a bundle on disk. By contrast, subpath is a relative path to a subdirectory inside the relevant global or localized resource directory, and should be nil if the resource file in question is not in a subdirectory. Where appropriate, localizationName is the name of a .lproj directory in the bundle, minus the .lproj extension; passing nil for localizationName retrieves only global resources, whereas using a method without this argument retrieves both global and localized resources (using the standard localization search algorithm). * @param name Argument converted to the Objective-C parameter of the same role. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. @@ -91,7 +88,6 @@ namespace cocoon static URL url_for_resource(const std::string& name, const std::string& ext, const std::string& subpath, const URL& bundle_url); /** * @brief Calls `-[NSBundle URLForResource:withExtension:subdirectory:localization:]`. - * @details Returns the file URL for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization. \@param name The name of the resource file. If \@c nil, the method returns the first resource file it finds that matches the remaining criteria. \@param ext The filename extension of the file to locate. If an empty string or \@c nil, the extension is assumed not to exist. \@param subpath The name of the bundle subdirectory to search. \@param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the \@c .lproj extension. \@return The file URL for the resource file or \@c nil if the file could not be located. * @param name Argument converted to the Objective-C parameter of the same role. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. @@ -101,7 +97,6 @@ namespace cocoon URL url_for_resource(const std::string& name, const std::string& ext, const std::string& subpath, const std::string& localization_name) const; /** * @brief Calls `-[NSBundle URLsForResourcesWithExtension:subdirectory:]`. - * @details Returns an array of file URLs for all resources identified by the specified file extension and located in the specified bundle subdirectory. \@param ext The filename extension of the files to locate. If an empty string or \@c nil, all files in \@c subpath are returned. \@param subpath The name of the bundle subdirectory. \@return An array of file URLs for the resource files or \@c nil if no files could be located. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -109,7 +104,6 @@ namespace cocoon std::vector ur_ls_for_resources_with_extension(const std::string& ext, const std::string& subpath) const; /** * @brief Calls `+[NSBundle URLsForResourcesWithExtension:subdirectory:inBundleWithURL:]`. - * @details Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, within the specified bundle. \@param ext The filename extension of the files to locate. If an empty string or \@c nil, all files in \@c subpath are returned. \@param subpath The name of the bundle subdirectory to search. \@param bundleURL The file URL of the bundle to search. \@return An array of file URLs for the resource files matching the criteria or an empty array if no files could be located. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. * @param bundle_url Argument converted to the Objective-C parameter of the same role. @@ -118,7 +112,6 @@ namespace cocoon static std::vector ur_ls_for_resources_with_extension(const std::string& ext, const std::string& subpath, const URL& bundle_url); /** * @brief Calls `-[NSBundle URLsForResourcesWithExtension:subdirectory:localization:]`. - * @details Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization. \@param ext The filename extension of the files to locate. If an empty string or \@c nil, all files in \@c subpath are returned. \@param subpath The name of the bundle subdirectory to search. \@param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the \@c .lproj extension. \@return An array containing the file URLs for all bundle resources matching the specified criteria. Returns an empty array if no matching resource files are found. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. * @param localization_name Argument converted to the Objective-C parameter of the same role. @@ -127,14 +120,12 @@ namespace cocoon std::vector ur_ls_for_resources_with_extension(const std::string& ext, const std::string& subpath, const std::string& localization_name) const; /** * @brief Calls `+[NSBundle bundleForClass:]`. - * @details Returns the 'NSBundle' object with which the specified class is associated. \@param aClass A class. \@return The 'NSBundle' object that dynamically loaded \@c aClass (a loadable bundle), the 'NSBundle' object for the framework in which \@c aClass is defined, or the main bundle object if \@c aClass was not dynamically loaded or is not defined in a framework. * @param a_class Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Bundle bundle_for_class(const std::string& a_class); /** * @brief Calls `-[NSBundle classNamed:]`. - * @details Returns the \@c Class object for the specified name. If the bundle's executable code is not yet loaded, this method dynamically loads it into memory. \@param className The name of a class. \@return The \@c Class object for \@c className. Returns \@c nil if \@c className is not one of the classes associated with the receiver or if there is an error loading the executable code. * @param class_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -153,7 +144,6 @@ namespace cocoon Image image_for_resource(const std::string& name) const; /** * @brief Calls `-[NSBundle loadAndReturnError:]`. - * @details Loads the bundle's executable code and returns any errors. If this method returns \@c NO and you pass a value for the \@c error parameter, a suitable error object is returned. Potential errors include \@c NSFileNoSuchFileError, \@c NSExecutableNotLoadableError, \@c NSExecutableArchitectureMismatchError, \@c NSExecutableRuntimeMismatchError, \@c NSExecutableLoadError, and \@c NSExecutableLinkError. \@param error On output, this variable may contain an error object indicating why the bundle's executable could not be loaded. \@return \@c YES if the bundle's executable code was loaded successfully or was already loaded; otherwise, \@c NO. * @return The converted Objective-C result. */ bool load_and_return_error() const; @@ -175,7 +165,7 @@ namespace cocoon AttributedString localized_attributed_string_for_key(const std::string& key, const std::string& value, const std::string& table_name) const; /** * @brief Calls `-[NSBundle localizedStringForKey:value:table:]`. - * @details Returns a localized version of the string designated by the specified key and residing in the specified table. \@param key The key for a string in the table identified by \@c tableName. \@param value The value to return if \@c key is \@c nil or if a localized string for \@c key can't be found in the table. \@param tableName The receiver's string table to search. If \@c nil or an empty string, the method attempts to use the table in \@c Localizable.strings. \@return A localized version of the string designated by \@c key in table \@c tableName. + * @details Methods for retrieving localized strings. * @param key Argument converted to the Objective-C parameter of the same role. * @param value Argument converted to the Objective-C parameter of the same role. * @param table_name Argument converted to the Objective-C parameter of the same role. @@ -194,14 +184,12 @@ namespace cocoon std::string localized_string_for_key(const std::string& key, const std::string& value, const std::string& table_name, const std::vector& localizations) const; /** * @brief Calls `-[NSBundle objectForInfoDictionaryKey:]`. - * @details Returns the value associated with the specified key in the receiver's information property list. Use of this method is preferred over other access methods because it returns the localized value of a key when one is available. \@param key A key in the receiver's property list. \@return The value associated with \@c key in the receiver's property list (\@c Info.plist). The localized value of a key is returned when one is available. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object object_for_info_dictionary_key(const std::string& key) const; /** * @brief Calls `-[NSBundle pathForAuxiliaryExecutable:]`. - * @details Returns the full pathname of the executable with the specified name in the receiver's bundle. This method returns the appropriate path for modern application and framework bundles. This method may not return a path for non-standard bundle formats or for some older bundle formats. \@param executableName The name of an executable file. \@return The full pathname of the executable in the receiver's bundle. * @param executable_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -214,7 +202,6 @@ namespace cocoon std::string path_for_image_resource(const std::string& name) const; /** * @brief Calls `-[NSBundle pathForResource:ofType:]`. - * @details Returns the full pathname for the resource identified by the specified name and file extension. The method first looks for a matching resource file in the non-localized resource directory of the specified bundle. If a matching resource file is not found, it then looks in the top level of an available language-specific \@c .lproj folder. \@param name The name of the resource file. If \@c nil, the method returns the first resource file it finds with the specified extension. \@param ext The filename extension of the file to locate. If an empty string or \@c nil, the extension is assumed not to exist. \@return The full pathname for the resource file, or \@c nil if the file could not be located. * @param name Argument converted to the Objective-C parameter of the same role. * @param ext Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -222,7 +209,6 @@ namespace cocoon std::string path_for_resource(const std::string& name, const std::string& ext) const; /** * @brief Calls `-[NSBundle pathForResource:ofType:inDirectory:]`. - * @details Returns the full pathname for the resource identified by the specified name and file extension and located in the specified bundle subdirectory. \@param name The name of the resource file. If \@c nil, the method returns the first resource file it finds that matches the remaining criteria. \@param ext The filename extension of the files to locate. If an empty string or \@c nil, all files in \@c subpath and its subdirectories are returned. \@param subpath The name of the bundle subdirectory. \@return The full pathname for the resource file, or \@c nil if the file could not be located. * @param name Argument converted to the Objective-C parameter of the same role. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. @@ -231,7 +217,6 @@ namespace cocoon std::string path_for_resource(const std::string& name, const std::string& ext, const std::string& subpath) const; /** * @brief Calls `-[NSBundle pathForResource:ofType:inDirectory:forLocalization:]`. - * @details Returns the full pathname for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization. \@param name The name of the resource file. If \@c nil, the method returns the first resource file it finds that matches the remaining criteria. \@param ext The filename extension of the files to locate. If an empty string or \@c nil, the extension is assumed not to exist. \@param subpath The name of the bundle subdirectory to search. \@param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the \@c .lproj extension. \@return The full pathname for the resource file or \@c nil if the file could not be located. * @param name Argument converted to the Objective-C parameter of the same role. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. @@ -247,7 +232,6 @@ namespace cocoon std::string path_for_sound_resource(const std::string& name) const; /** * @brief Calls `-[NSBundle pathsForResourcesOfType:inDirectory:]`. - * @details Returns an array containing the pathnames for all bundle resources having the specified filename extension and residing in the resource subdirectory. \@param ext The filename extension of the files to locate. If an empty string or \@c nil, all files in \@c subpath are returned. \@param subpath The name of the bundle subdirectory to search. \@return An array containing the full pathnames for all bundle resources matching the specified criteria. Returns an empty array if no matching resource files are found. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -255,7 +239,6 @@ namespace cocoon std::vector paths_for_resources_of_type(const std::string& ext, const std::string& subpath) const; /** * @brief Calls `-[NSBundle pathsForResourcesOfType:inDirectory:forLocalization:]`. - * @details Returns an array containing the file for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization. \@param ext The filename extension of the files to locate. If an empty string or \@c nil, all files in \@c subpath are returned. \@param subpath The name of the bundle subdirectory to search. \@param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the \@c .lproj extension. \@return An array containing the full pathnames for all bundle resources matching the specified criteria. Returns an empty array if no matching resource files are found. * @param ext Argument converted to the Objective-C parameter of the same role. * @param subpath Argument converted to the Objective-C parameter of the same role. * @param localization_name Argument converted to the Objective-C parameter of the same role. @@ -264,14 +247,12 @@ namespace cocoon std::vector paths_for_resources_of_type(const std::string& ext, const std::string& subpath, const std::string& localization_name) const; /** * @brief Calls `+[NSBundle preferredLocalizationsFromArray:]`. - * @details Returns one or more localizations from the specified list that a bundle object would use to locate resources for the current user. This method does not return all localizations in preference order but only those from which \@c NSBundle would get localized content, typically either a single non-region-specific localization or a region-specific localization followed by a corresponding non-region-specific localization as a fallback. \@param localizationsArray An array of \@c NSString objects, each of which specifies the language ID for a localization that the bundle supports. \@return An array of \@c NSString objects containing the preferred localizations, ordered according to the user's language preferences. * @param localizations_array Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector preferred_localizations_from_array(const std::vector& localizations_array); /** * @brief Calls `+[NSBundle preferredLocalizationsFromArray:forPreferences:]`. - * @details Returns locale identifiers for which a bundle would provide localized content, given a specified list of candidates for a user's language preferences. \@param localizationsArray An array of identifiers, each corresponding to a localization that a bundle can support. \@param preferencesArray An array of BCP 47 language codes corresponding to a user's preferred languages. If \@c nil, the method uses the current user's language preferences. \@return An array of locale identifiers, ordered according to user preference. If none of the user-preferred localizations are available, this method returns one of the values in \@c localizationsArray. * @param localizations_array Argument converted to the Objective-C parameter of the same role. * @param preferences_array Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -279,175 +260,150 @@ namespace cocoon static std::vector preferred_localizations_from_array(const std::vector& localizations_array, const std::vector& preferences_array); /** * @brief Calls `-[NSBundle preflightAndReturnError:]`. - * @details Returns a Boolean value indicating whether the bundle's executable code could be loaded successfully. This method does not actually load the bundle's executable code. Instead, it performs several checks to see if the code could be loaded and with one exception returns the same errors that would occur during an actual load operation. \@param error On output, this variable may contain an error object indicating why the bundle's executable could not be loaded. \@return \@c YES if the bundle's executable code could be loaded successfully or is already loaded; otherwise, \@c NO. * @return The converted Objective-C result. */ bool preflight_and_return_error() const; /** * @brief Calls `-[NSBundle unload]`. - * @details Unloads the code associated with the receiver. This method attempts to unload a bundle's executable code using the underlying dynamic loader (typically \@c dyld). You may use this method to unload plug-in and framework bundles when you no longer need the code they contain. It is the responsibility of the caller to ensure that no in-memory objects or data structures refer to the code being unloaded. \@return \@c YES if the bundle was successfully unloaded or was not already loaded; otherwise, \@c NO if the bundle could not be unloaded. * @return The converted Objective-C result. */ bool unload() const; /** * @brief Returns the `allBundles` property of `NSBundle`. - * @details An array of all the application's non-framework bundles. The returned array includes the main bundle and all bundles that have been dynamically created but doesn't contain any bundles that represent frameworks. * @return The converted Objective-C result. */ static std::vector all_bundles(); /** * @brief Returns the `allFrameworks` property of `NSBundle`. - * @details An array of all of the application's bundles that represent frameworks. The returned array includes frameworks that are linked into an application when the application is built and bundles for frameworks that have been dynamically created. Only frameworks with one or more Objective-C classes in them are included. * @return The converted Objective-C result. */ static std::vector all_frameworks(); /** * @brief Returns the `appStoreReceiptURL` property of `NSBundle`. - * @details The file URL for the bundle's App Store receipt. Use this app bundle property to locate the app receipt if it's present; this property is \@c nil if the receipt isn't present. In the rare case a receipt is invalid or missing in an app that a user downloads from the App Store, use \@c SKReceiptRefreshRequest to request a new receipt. * @return The converted Objective-C result. */ URL app_store_receipt_url() const; /** * @brief Returns the `builtInPlugInsPath` property of `NSBundle`. - * @details The full pathname of the receiver's subdirectory containing plug-ins. This is the appropriate path for modern application and framework bundles. This may not be a path for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ std::string built_in_plug_ins_path() const; /** * @brief Returns the `builtInPlugInsURL` property of `NSBundle`. - * @details The file URL of the receiver's subdirectory containing plug-ins. This is the appropriate path for modern application and framework bundles. This may not be a URL for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ URL built_in_plug_ins_url() const; /** * @brief Returns the `bundleIdentifier` property of `NSBundle`. - * @details The receiver's bundle identifier. The bundle identifier is defined by the \@c CFBundleIdentifier key in the bundle's information property list. + * @details Methods for obtaining various information about a bundle. * @return The converted Objective-C result. */ std::string bundle_identifier() const; /** * @brief Returns the `bundlePath` property of `NSBundle`. - * @details The full pathname of the receiver's bundle directory. * @return The converted Objective-C result. */ std::string bundle_path() const; /** * @brief Returns the `bundleURL` property of `NSBundle`. - * @details The full URL of the receiver's bundle directory. + * @details Methods for locating various components of a bundle. * @return The converted Objective-C result. */ URL bundle_url() const; /** * @brief Returns the `developmentLocalization` property of `NSBundle`. - * @details The localization for the development language. This property corresponds to the value in the \@c CFBundleDevelopmentRegion key of the bundle's property list (\@c Info.plist). * @return The converted Objective-C result. */ std::string development_localization() const; /** * @brief Returns the `executableArchitectures` property of `NSBundle`. - * @details An array of numbers indicating the architecture types supported by the bundle's executable. An array of \@c NSNumber objects, each of which contains an integer value corresponding to a supported processor architecture. If the bundle does not contain a Mach-O executable, this is \@c nil. * @return The converted Objective-C result. */ std::vector executable_architectures() const; /** * @brief Returns the `executablePath` property of `NSBundle`. - * @details The full pathname of the receiver's executable file. * @return The converted Objective-C result. */ std::string executable_path() const; /** * @brief Returns the `executableURL` property of `NSBundle`. - * @details The file URL of the receiver's executable file. * @return The converted Objective-C result. */ URL executable_url() const; /** * @brief Returns the `infoDictionary` property of `NSBundle`. - * @details A dictionary, constructed from the bundle's \@c Info.plist file, that contains information about the receiver. If the bundle does not contain an \@c Info.plist file, this dictionary contains only private keys that are used internally by the \@c NSBundle class. Common keys for accessing the values of the dictionary are \@c CFBundleIdentifier, \@c NSMainNibFile, and \@c NSPrincipalClass. * @return The converted Objective-C result. */ std::map info_dictionary() const; /** * @brief Returns the `loaded` property of `NSBundle`. - * @details The load status of a bundle. \@c YES if the bundle's code is currently loaded, otherwise \@c NO. * @return The converted Objective-C result. */ bool is_loaded() const; /** * @brief Returns the `localizations` property of `NSBundle`. - * @details A list of all the localizations contained in the bundle. An array of \@c NSString objects containing language IDs for all the localizations contained in the bundle. * @return The converted Objective-C result. */ std::vector localizations() const; /** * @brief Returns the `localizedInfoDictionary` property of `NSBundle`. - * @details A dictionary with the keys from the bundle's localized property list. This property uses the preferred localization for the current user when determining which resources to include. If the preferred localization is not available, this property chooses the most appropriate localization found in the bundle. * @return The converted Objective-C result. */ std::map localized_info_dictionary() const; /** * @brief Returns the `mainBundle` property of `NSBundle`. - * @details Returns the bundle object that contains the current executable. The main bundle lets you access the resources in the same directory as the currently running executable. For a running app or code running in a framework, the main bundle offers access to the app's bundle directory. This method may return a valid bundle object even for unbundled apps. It may also return 'nil' if the bundle object could not be created, so always check the return value. + * @details Methods for creating or retrieving bundle instances. * @return The converted Objective-C result. */ static Bundle main_bundle(); /** * @brief Returns the `preferredLocalizations` property of `NSBundle`. - * @details An ordered list of preferred localizations contained in the bundle. An array of \@c NSString objects containing language IDs for localizations in the bundle. The strings are ordered according to the user's language preferences and available localizations. + * @details Methods for dealing with localizations. * @return The converted Objective-C result. */ std::vector preferred_localizations() const; /** * @brief Returns the `principalClass` property of `NSBundle`. - * @details The bundle's principal class. This property is set after ensuring that the code containing the definition of the class is dynamically loaded. If the bundle encounters errors in loading or if it can't find the executable code file in the bundle directory, this property is \@c nil. The bundle obtains the principal class from the information dictionary using the key \@c NSPrincipalClass. For non-loadable bundles (applications and frameworks), if the principal class is not specified in the property list, this property is \@c nil. * @return The converted Objective-C result. */ std::string principal_class() const; /** * @brief Returns the `privateFrameworksPath` property of `NSBundle`. - * @details The full pathname of the bundle's subdirectory containing private frameworks. This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ std::string private_frameworks_path() const; /** * @brief Returns the `privateFrameworksURL` property of `NSBundle`. - * @details The file URL of the bundle's subdirectory containing private frameworks. This property contains the appropriate path for modern application and framework bundles. This property may not be a URL for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ URL private_frameworks_url() const; /** * @brief Returns the `resourcePath` property of `NSBundle`. - * @details The full pathname of the bundle's subdirectory containing resources. * @return The converted Objective-C result. */ std::string resource_path() const; /** * @brief Returns the `resourceURL` property of `NSBundle`. - * @details The file URL of the bundle's subdirectory containing resource files. This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ URL resource_url() const; /** * @brief Returns the `sharedFrameworksPath` property of `NSBundle`. - * @details The full pathname of the bundle's subdirectory containing shared frameworks. This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ std::string shared_frameworks_path() const; /** * @brief Returns the `sharedFrameworksURL` property of `NSBundle`. - * @details The file URL of the receiver's subdirectory containing shared frameworks. This property contains the appropriate path for modern application and framework bundles. This property may not contain a URL for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ URL shared_frameworks_url() const; /** * @brief Returns the `sharedSupportPath` property of `NSBundle`. - * @details The full pathname of the bundle's subdirectory containing shared support files. This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ std::string shared_support_path() const; /** * @brief Returns the `sharedSupportURL` property of `NSBundle`. - * @details The file URL of the bundle's subdirectory containing shared support files. This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats. * @return The converted Objective-C result. */ URL shared_support_url() const; diff --git a/include/generated/byte_count_formatter.h b/include/generated/byte_count_formatter.h index 8f197d4c..b88a4426 100644 --- a/include/generated/byte_count_formatter.h +++ b/include/generated/byte_count_formatter.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSByteCountFormatter` (Foundation). - * @details A formatter that converts a byte count value into a localized description that is formatted with the appropriate byte modifier (KB, MB, GB and so on). > Tip: > In Swift, you can use ''ByteCountFormatStyle'' or ''Measurement/FormatStyle/ByteCount'' rather than ''ByteCountFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -57,14 +56,14 @@ namespace cocoon std::string string_for_object_value(const Object& obj) const; /** * @brief Calls `-[NSByteCountFormatter stringFromByteCount:]`. - * @details Converts a byte count into a string without creating an 'NSNumber' object. This is a convenience method on 'stringForObjectValue:'. \@param byteCount The byte count. \@return A string containing the formatted 'byteCount' value. + * @details Convenience method on stringForObjectValue:. Convert a byte count into a string without creating an NSNumber. * @param byte_count Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_byte_count(std::int64_t byte_count) const; /** * @brief Calls `+[NSByteCountFormatter stringFromByteCount:countStyle:]`. - * @details Converts a byte count into the specified string format without creating an 'NSNumber' object. If you need to specify options other than 'countStyle', create an instance of 'NSByteCountFormatter' first. \@param byteCount The byte count. \@param countStyle The formatter style. See 'NSByteCountFormatterCountStyle' for possible values. \@return A string containing the formatted 'byteCount' value. + * @details Shortcut for converting a byte count into a string without creating an NSByteCountFormatter and an NSNumber. If you need to specify options other than countStyle, create an instance of NSByteCountFormatter first. * @param byte_count Argument converted to the Objective-C parameter of the same role. * @param count_style Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -87,109 +86,107 @@ namespace cocoon static std::string string_from_measurement(const MeasurementBase& measurement, ByteCountFormatterCountStyle count_style); /** * @brief Returns the `adaptive` property of `NSByteCountFormatter`. - * @details Determines the display style of the size representation. The "adaptive" algorithm is platform specific and uses a different number of fraction digits based on the magnitude (in OS X v10.8: 0 fraction digits for bytes and KB; 1 fraction digits for MB; 2 for GB and above). Otherwise the result always tries to show at least three significant digits, introducing fraction digits as necessary. Default is 'YES'. + * @details Choose the display style. The "adaptive" algorithm is platform specific and uses a different number of fraction digits based on the magnitude (in 10.8: 0 fraction digits for bytes and KB; 1 fraction digits for MB; 2 for GB and above). Otherwise the result always tries to show at least three significant digits, introducing fraction digits as necessary. Default is YES. * @return The converted Objective-C result. */ bool is_adaptive() const; /** * @brief Sets the `adaptive` property of `NSByteCountFormatter`. - * @details Determines the display style of the size representation. The "adaptive" algorithm is platform specific and uses a different number of fraction digits based on the magnitude (in OS X v10.8: 0 fraction digits for bytes and KB; 1 fraction digits for MB; 2 for GB and above). Otherwise the result always tries to show at least three significant digits, introducing fraction digits as necessary. Default is 'YES'. + * @details Choose the display style. The "adaptive" algorithm is platform specific and uses a different number of fraction digits based on the magnitude (in 10.8: 0 fraction digits for bytes and KB; 1 fraction digits for MB; 2 for GB and above). Otherwise the result always tries to show at least three significant digits, introducing fraction digits as necessary. Default is YES. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_adaptive(bool value) const; /** * @brief Returns the `allowedUnits` property of `NSByteCountFormatter`. - * @details Specify the units that can be used in the output. If the value is 'NSByteCountFormatterUseDefault', the formatter uses platform-appropriate settings; otherwise only the specified units are used. > Note: ZB and YB cannot be covered by the range of possible values, but you can still choose to use these units to get fractional display ("0.0035 ZB" for instance). + * @details Specify the units that can be used in the output. If NSByteCountFormatterUseDefault, uses platform-appropriate settings; otherwise will only use the specified units. This is the default value. Note that ZB and YB cannot be covered by the range of possible values, but you can still choose to use these units to get fractional display ("0.0035 ZB" for instance). * @return The converted Objective-C result. */ ByteCountFormatterUnits allowed_units() const; /** * @brief Sets the `allowedUnits` property of `NSByteCountFormatter`. - * @details Specify the units that can be used in the output. If the value is 'NSByteCountFormatterUseDefault', the formatter uses platform-appropriate settings; otherwise only the specified units are used. > Note: ZB and YB cannot be covered by the range of possible values, but you can still choose to use these units to get fractional display ("0.0035 ZB" for instance). + * @details Specify the units that can be used in the output. If NSByteCountFormatterUseDefault, uses platform-appropriate settings; otherwise will only use the specified units. This is the default value. Note that ZB and YB cannot be covered by the range of possible values, but you can still choose to use these units to get fractional display ("0.0035 ZB" for instance). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allowed_units(ByteCountFormatterUnits value) const; /** * @brief Returns the `allowsNonnumericFormatting` property of `NSByteCountFormatter`. - * @details Determines whether to allow more natural display of some values. Displays a more natural display of some values, such as zero, where it may be displayed as "Zero KB", ignoring all other flags or options (with the exception of 'NSByteCountFormatterUseBytes', which would generate "Zero bytes"). The result is appropriate for standalone output. Special handling of certain values such as zero is especially important in some languages, so it's highly recommended that this property be left in its default state. Default value is 'YES'. + * @details Choose whether to allow more natural display of some values, such as zero, where it may be displayed as "Zero KB," ignoring all other flags or options (with the exception of NSByteCountFormatterUseBytes, which would generate "Zero bytes"). The result is appropriate for standalone output. Default value is YES. Special handling of certain values such as zero is especially important in some languages, so it's highly recommended that this property be left in its default state. * @return The converted Objective-C result. */ bool allows_nonnumeric_formatting() const; /** * @brief Sets the `allowsNonnumericFormatting` property of `NSByteCountFormatter`. - * @details Determines whether to allow more natural display of some values. Displays a more natural display of some values, such as zero, where it may be displayed as "Zero KB", ignoring all other flags or options (with the exception of 'NSByteCountFormatterUseBytes', which would generate "Zero bytes"). The result is appropriate for standalone output. Special handling of certain values such as zero is especially important in some languages, so it's highly recommended that this property be left in its default state. Default value is 'YES'. + * @details Choose whether to allow more natural display of some values, such as zero, where it may be displayed as "Zero KB," ignoring all other flags or options (with the exception of NSByteCountFormatterUseBytes, which would generate "Zero bytes"). The result is appropriate for standalone output. Default value is YES. Special handling of certain values such as zero is especially important in some languages, so it's highly recommended that this property be left in its default state. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_nonnumeric_formatting(bool value) const; /** * @brief Returns the `countStyle` property of `NSByteCountFormatter`. - * @details Specify the number of bytes to be used for kilobytes. The default setting is 'NSByteCountFormatterCountStyleFile', which is the system specific value for file and storage sizes. + * @details Specify how the count is displayed by indicating the number of bytes to be used for kilobyte. The default setting is NSByteCountFormatterFileCount, which is the system specific value for file and storage sizes. * @return The converted Objective-C result. */ ByteCountFormatterCountStyle count_style() const; /** * @brief Sets the `countStyle` property of `NSByteCountFormatter`. - * @details Specify the number of bytes to be used for kilobytes. The default setting is 'NSByteCountFormatterCountStyleFile', which is the system specific value for file and storage sizes. + * @details Specify how the count is displayed by indicating the number of bytes to be used for kilobyte. The default setting is NSByteCountFormatterFileCount, which is the system specific value for file and storage sizes. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_count_style(ByteCountFormatterCountStyle value) const; /** * @brief Returns the `formattingContext` property of `NSByteCountFormatter`. - * @details Specify the formatting context for the formatted string. The default value is 'NSFormattingContextUnknown'. + * @details Specify the formatting context for the formatted string. Default is NSFormattingContextUnknown. * @return The converted Objective-C result. */ FormattingContext formatting_context() const; /** * @brief Sets the `formattingContext` property of `NSByteCountFormatter`. - * @details Specify the formatting context for the formatted string. The default value is 'NSFormattingContextUnknown'. + * @details Specify the formatting context for the formatted string. Default is NSFormattingContextUnknown. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_formatting_context(FormattingContext value) const; /** * @brief Returns the `includesActualByteCount` property of `NSByteCountFormatter`. - * @details Determines whether to include the number of bytes after the formatted string. Setting this value to 'YES' causes the byte count to be displayed parenthetically (localized as appropriate), for instance "723 KB (722,842 bytes)". This will happen only if needed, that is, the first part is already not showing the exact byte count. If 'includesUnit' or 'includesCount' are 'NO', then this setting has no effect. Default value is 'NO'. + * @details Choose whether to parenthetically (localized as appropriate) display the actual number of bytes as well, for instance "723 KB (722,842 bytes)". This will happen only if needed, that is, the first part is already not showing the exact byte count. If includesUnit or includesCount are NO, then this setting has no effect. Default value is NO. * @return The converted Objective-C result. */ bool includes_actual_byte_count() const; /** * @brief Sets the `includesActualByteCount` property of `NSByteCountFormatter`. - * @details Determines whether to include the number of bytes after the formatted string. Setting this value to 'YES' causes the byte count to be displayed parenthetically (localized as appropriate), for instance "723 KB (722,842 bytes)". This will happen only if needed, that is, the first part is already not showing the exact byte count. If 'includesUnit' or 'includesCount' are 'NO', then this setting has no effect. Default value is 'NO'. + * @details Choose whether to parenthetically (localized as appropriate) display the actual number of bytes as well, for instance "723 KB (722,842 bytes)". This will happen only if needed, that is, the first part is already not showing the exact byte count. If includesUnit or includesCount are NO, then this setting has no effect. Default value is NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_actual_byte_count(bool value) const; /** * @brief Returns the `includesCount` property of `NSByteCountFormatter`. - * @details Determines whether to include the count in the resulting formatted string. If set to 'YES' and 'includesUnit' is set to 'NO', no unit is displayed. For example, a value of 723 KB is formatted as "723". You can set this property and 'includesUnit' individually to get both parts, separately. Note that putting them together yourself via string concatenation may be incorrect for some locales. The default value is 'YES'. * @return The converted Objective-C result. */ bool includes_count() const; /** * @brief Sets the `includesCount` property of `NSByteCountFormatter`. - * @details Determines whether to include the count in the resulting formatted string. If set to 'YES' and 'includesUnit' is set to 'NO', no unit is displayed. For example, a value of 723 KB is formatted as "723". You can set this property and 'includesUnit' individually to get both parts, separately. Note that putting them together yourself via string concatenation may be incorrect for some locales. The default value is 'YES'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_count(bool value) const; /** * @brief Returns the `includesUnit` property of `NSByteCountFormatter`. - * @details Determines whether to include the units in the resulting formatted string. If set to 'YES' and 'includesCount' is set to 'NO', no count is displayed. For example, a value of 723 KB is formatted as "KB". You can set this property and 'includesCount' individually to get both parts, separately. Note that putting them together yourself via string concatenation may be incorrect for some locales. The default value is 'YES'. + * @details Choose whether to include the number or the units in the resulting formatted string. (For example, instead of 723 KB, returns "723" or "KB".) You can call the API twice to get both parts, separately. But note that putting them together yourself via string concatenation may be wrong for some locales; so use this functionality with care. Both of these values are YES by default. Setting both to NO will unsurprisingly result in an empty string. * @return The converted Objective-C result. */ bool includes_unit() const; /** * @brief Sets the `includesUnit` property of `NSByteCountFormatter`. - * @details Determines whether to include the units in the resulting formatted string. If set to 'YES' and 'includesCount' is set to 'NO', no count is displayed. For example, a value of 723 KB is formatted as "KB". You can set this property and 'includesCount' individually to get both parts, separately. Note that putting them together yourself via string concatenation may be incorrect for some locales. The default value is 'YES'. + * @details Choose whether to include the number or the units in the resulting formatted string. (For example, instead of 723 KB, returns "723" or "KB".) You can call the API twice to get both parts, separately. But note that putting them together yourself via string concatenation may be wrong for some locales; so use this functionality with care. Both of these values are YES by default. Setting both to NO will unsurprisingly result in an empty string. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_unit(bool value) const; /** * @brief Returns the `zeroPadsFractionDigits` property of `NSByteCountFormatter`. - * @details Determines whether to zero pad fraction digits so a consistent number of characters is displayed in a representation. Displaying values using zero pad fraction digits causes a consistent number of fraction digits to be displayed, causing updating displays to remain more stable. For instance, if the adaptive algorithm is used, this option formats 1.19 and 1.2 GB as "1.19 GB" and "1.20 GB", respectively, while without the option the latter would be displayed as "1.2 GB". Default value is 'NO'. + * @details Choose whether to zero pad fraction digits so a consistent number of fraction digits are displayed, causing updating displays to remain more stable. For instance, if the adaptive algorithm is used, this option formats 1.19 and 1.2 GB as "1.19 GB" and "1.20 GB" respectively, while without the option the latter would be displayed as "1.2 GB". Default value is NO. * @return The converted Objective-C result. */ bool zero_pads_fraction_digits() const; /** * @brief Sets the `zeroPadsFractionDigits` property of `NSByteCountFormatter`. - * @details Determines whether to zero pad fraction digits so a consistent number of characters is displayed in a representation. Displaying values using zero pad fraction digits causes a consistent number of fraction digits to be displayed, causing updating displays to remain more stable. For instance, if the adaptive algorithm is used, this option formats 1.19 and 1.2 GB as "1.19 GB" and "1.20 GB", respectively, while without the option the latter would be displayed as "1.2 GB". Default value is 'NO'. + * @details Choose whether to zero pad fraction digits so a consistent number of fraction digits are displayed, causing updating displays to remain more stable. For instance, if the adaptive algorithm is used, this option formats 1.19 and 1.2 GB as "1.19 GB" and "1.20 GB" respectively, while without the option the latter would be displayed as "1.2 GB". Default value is NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_zero_pads_fraction_digits(bool value) const; diff --git a/include/generated/cache_base.h b/include/generated/cache_base.h index 7b6b4393..655c87f3 100644 --- a/include/generated/cache_base.h +++ b/include/generated/cache_base.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSCache` (Foundation). - * @details A mutable collection you use to temporarily store transient key-value pairs that are subject to eviction when resources are low. Cache objects differ from other mutable collections in a few ways: - The ''NSCache'' class incorporates various auto-eviction policies, which ensure that a cache doesn't use too much of the system's memory. If memory is needed by other applications, these policies remove some items from the cache, minimizing its memory footprint. - You can add, remove, and query items in the cache from different threads without having to lock the cache yourself. - Unlike an ''NSMutableDictionary'' object, a cache does not copy the key objects that are put into it. You typically use ''NSCache'' objects to temporarily store objects with transient data that are expensive to create. Reusing these objects can provide performance benefits, because their values do not have to be recalculated. However, the objects are not critical to the application and can be discarded if memory is tight. If discarded, their values will have to be recomputed again when needed. Objects that have subcomponents that can be discarded when not being used can adopt the ''NSDiscardableContent'' protocol to improve cache eviction behavior. By default, ''NSDiscardableContent'' objects in a cache are automatically removed if their content is discarded, although this automatic removal policy can be changed. If an ''NSDiscardableContent'' object is put into the cache, the cache calls ''NSDiscardableContent/discardContentIfPossible()'' on it upon its removal. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref Cache to supply KeyType, ObjectType. * @@ -49,32 +48,27 @@ namespace cocoon explicit CacheBase(Adopt adopt); /** * @brief Calls `-[NSCache objectForKey:]`. - * @details Returns the value associated with a given key. - Parameter key: An object identifying the value. - Returns: The value associated with 'key', or 'nil' if no value is associated with 'key'. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object object_for_key(const Object& key) const; /** * @brief Calls `-[NSCache removeAllObjects]`. - * @details Empties the cache. */ void remove_all_objects() const; /** * @brief Calls `-[NSCache removeObjectForKey:]`. - * @details Removes the value of the specified key in the cache. - Parameter key: The key identifying the value to be removed. * @param key Argument converted to the Objective-C parameter of the same role. */ void remove_object_for_key(const Object& key) const; /** * @brief Calls `-[NSCache setObject:forKey:]`. - * @details Sets the value of the specified key in the cache. Unlike an 'NSMutableDictionary' object, a cache does not copy the key objects that are put into it. - Parameter obj: The object to be stored in the cache. - Parameter key: The key with which to associate the value. * @param obj Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void set_object(const Object& obj, const Object& key) const; /** * @brief Calls `-[NSCache setObject:forKey:cost:]`. - * @details Sets the value of the specified key in the cache, and associates the key-value pair with the specified cost. The 'cost' value is used to compute a sum encompassing the costs of all the objects in the cache. When memory is limited or when the total cost of the cache eclipses the maximum allowed total cost, the cache could begin an eviction process to remove some of its elements. Unlike an 'NSMutableDictionary' object, a cache does not copy the key objects that are put into it. - Parameter obj: The object to store in the cache. - Parameter key: The key with which to associate the value. - Parameter g: The cost with which to associate the key-value pair. * @param obj Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. * @param g Argument converted to the Objective-C parameter of the same role. @@ -82,49 +76,41 @@ namespace cocoon void set_object(const Object& obj, const Object& key, std::uint64_t g) const; /** * @brief Returns the `countLimit` property of `NSCache`. - * @details The maximum number of objects the cache should hold. If '0', there is no count limit. The default value is '0'. This is not a strict limit -- if the cache goes over the limit, an object in the cache could be evicted instantly, later, or possibly never, depending on the implementation details of the cache. * @return The converted Objective-C result. */ std::uint64_t count_limit() const; /** * @brief Sets the `countLimit` property of `NSCache`. - * @details The maximum number of objects the cache should hold. If '0', there is no count limit. The default value is '0'. This is not a strict limit -- if the cache goes over the limit, an object in the cache could be evicted instantly, later, or possibly never, depending on the implementation details of the cache. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_count_limit(std::uint64_t value) const; /** * @brief Returns the `evictsObjectsWithDiscardedContent` property of `NSCache`. - * @details Whether the cache will automatically evict discardable-content objects whose content has been discarded. If 'YES', the cache will evict a discardable-content object after its content is discarded. If 'NO', it will not. The default value is 'YES'. * @return The converted Objective-C result. */ bool evicts_objects_with_discarded_content() const; /** * @brief Sets the `evictsObjectsWithDiscardedContent` property of `NSCache`. - * @details Whether the cache will automatically evict discardable-content objects whose content has been discarded. If 'YES', the cache will evict a discardable-content object after its content is discarded. If 'NO', it will not. The default value is 'YES'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_evicts_objects_with_discarded_content(bool value) const; /** * @brief Returns the `name` property of `NSCache`. - * @details The name of the cache. The default value is an empty string (""). * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSCache`. - * @details The name of the cache. The default value is an empty string (""). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; /** * @brief Returns the `totalCostLimit` property of `NSCache`. - * @details The maximum total cost that the cache can hold before it starts evicting objects. If '0', there is no total cost limit. The default value is '0'. This is not a strict limit, and if the cache goes over the limit, an object in the cache could be evicted instantly, at a later point in time, or possibly never, all depending on the implementation details of the cache. * @return The converted Objective-C result. */ std::uint64_t total_cost_limit() const; /** * @brief Sets the `totalCostLimit` property of `NSCache`. - * @details The maximum total cost that the cache can hold before it starts evicting objects. If '0', there is no total cost limit. The default value is '0'. This is not a strict limit, and if the cache goes over the limit, an object in the cache could be evicted instantly, at a later point in time, or possibly never, all depending on the implementation details of the cache. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_total_cost_limit(std::uint64_t value) const; diff --git a/include/generated/cached_url_response.h b/include/generated/cached_url_response.h index ede93e94..7abe3333 100644 --- a/include/generated/cached_url_response.h +++ b/include/generated/cached_url_response.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCachedURLResponse` (Foundation). - * @details A cached response to a URL request. A ''CachedURLResponse'' object provides the server's response metadata in the form of a ''URLResponse'' object, along with an [NSData](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html\#//apple_ref/doc/uid/20001012-47169) object containing the actual cached content data. Its storage policy determines whether the response should be cached on disk, in memory, or not at all. Cached responses also contain a user info dictionary where you can store app-specific information about the cached item. The ''URLCache'' class stores and retrieves instances of ''CachedURLResponse''. + * @details \@class NSCachedURLResponse NSCachedURLResponse is a class whose objects functions as a wrapper for objects that are stored in the framework's caching system. It is used to maintain characteristics and attributes of a cached object. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -38,25 +38,25 @@ namespace cocoon explicit CachedURLResponse(Adopt adopt); /** * @brief Returns the `data` property of `NSCachedURLResponse`. - * @details The cached response's data. + * @details \@abstract Returns the data of the receiver. \@result The data of the receiver. * @return The converted Objective-C result. */ std::vector data() const; /** * @brief Returns the `response` property of `NSCachedURLResponse`. - * @details The URL response object associated with the instance. + * @details \@abstract Returns the response wrapped by this instance. \@result The response wrapped by this instance. * @return The converted Objective-C result. */ URLResponse response() const; /** * @brief Returns the `storagePolicy` property of `NSCachedURLResponse`. - * @details The cached response's storage policy. + * @details \@abstract Returns the NSURLCacheStoragePolicy constant of the receiver. \@result The NSURLCacheStoragePolicy constant of the receiver. * @return The converted Objective-C result. */ URLCacheStoragePolicy storage_policy() const; /** * @brief Returns the `userInfo` property of `NSCachedURLResponse`. - * @details The cached response's user info dictionary. + * @details \@abstract Returns the userInfo dictionary of the receiver. \@result The userInfo dictionary of the receiver. * @return The converted Objective-C result. */ std::vector> user_info() const; diff --git a/include/generated/calendar.h b/include/generated/calendar.h index 6f3bab9e..1e619a4f 100644 --- a/include/generated/calendar.h +++ b/include/generated/calendar.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCalendar` (Foundation). - * @details A definition of the relationships between calendar units and absolute points in time, providing features for calculation and comparison of dates. In Swift, this object bridges to ''Calendar''; use ''NSCalendar'' when you need reference semantics or other Foundation-specific behavior. ''NSCalendar'' objects encapsulate information about systems of reckoning time in which the beginning, length, and divisions of a year are defined. They provide information about the calendar and support for calendrical computations such as determining the range of a given calendrical unit and adding units to a given absolute time. ''NSCalendar'' is toll-free bridged with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. > Important: > The Swift overlay to the Foundation framework provides the ''Calendar'' structure, which bridges to the ''NSCalendar'' class. For more information about value types, see \. \#\#\# Locales and Calendars Most locales use the most widely used civil calendar, called the Gregorian calendar (''Identifier/gregorian''), but there remain exceptions to this trend. For example: - In Saudi Arabia, some locales use primarily the Islamic Umm al-Qura calendar (''Identifier/islamicUmmAlQura''). - In Ethiopia, some locales use primarily the Ethiopian calendar (''Identifier/ethiopicAmeteMihret'' or ''Identifier/ethiopicAmeteAlem''). - In Iran and Afghanistan, some locales use primarily the Persian calendar (''Identifier/persian''). - In Thailand, some locales use primarily the Buddhist calendar (''Identifier/buddhist''). Other locales use another calendar alongside the Gregorian calendar. For example: - India also uses the Indian national calendar (''Identifier/indian''). - Israel also uses the Hebrew calendar (''Identifier/hebrew''). - China mainland and other regions also use the Chinese calendar (''Identifier/chinese''), primarily to calculate astronomical date and Chinese traditional holidays. - Japan also uses the Japanese calendar (''Identifier/japanese''), primarily to add year names. Independent of any particular locale, certain calendars are used primarily to calculate dates for religious observances. Among these are the Buddhist (''Identifier/buddhist''), Coptic (''Identifier/coptic''), Hebrew (''Identifier/hebrew''), and Islamic (''Identifier/islamic'') calendars. \#\#\# How NSCalendar Models the Gregorian Calendar The Gregorian calendar was first introduced in 1582, as a replacement for the Julian Calendar. According to the Julian calendar, a leap day is added to February for any year with a number divisible by 4, which results in an annual disparity of 11 minutes, or 1 day every 128 years. The Gregorian calendar revised the rules for leap day calculation, by skipping the leap day for any year with a number divisible by 100, unless that year number is also divisible by 400, resulting in an annual disparity of only 26 seconds, or 1 day every 3323 years. To transition from the Julian calendar to the Gregorian calendar, 10 days were dropped from the Gregorian calendar (October 5–14). After the Gregorian calendar was introduced, many regions continued to use the Julian calendar, with Turkey being the last country or region to adopt the Gregorian calendar, in 1926. As a result of the staggered adoption, the transition period for regions at the time of adoption have different start dates and a different number of skipped days to account for the additional disparity from leap day calculations. ''NSCalendar'' models the behavior of a proleptic Gregorian calendar (as defined by ISO 8601:2004), which extends the Gregorian calendar backward in time from the date of its introduction. This behavior should be taken into account when working with dates created before the transition period of the affected locales. \#\#\# Calendar Arithmetic To do calendar arithmetic, you use ''NSDate'' objects in conjunction with a calendar. For example, to convert between a decomposed date in one calendar and another calendar, you must first convert the decomposed elements into a date using the first calendar, then decompose it using the second. ''NSDate'' provides the absolute scale and epoch (reference point) for dates and times, which can then be rendered into a particular calendar, for calendrical computations or user display. Two ''NSCalendar'' methods that return a date object, ''date(from:)'', ''date(byAdding:to:options:)'', take as a parameter an ''NSDateComponents'' object that describes the calendrical components required for the computation. You can provide as many components as you need (or choose to). When there is incomplete information to compute an absolute time, default values similar to '0' and '1' are usually chosen by a calendar, but this is a calendar-specific choice. If you provide inconsistent information, calendar-specific disambiguation is performed (which may involve ignoring one or more of the parameters). Related methods (''components(:from:)'' and ''components(:from:to:options:)-84y5w'') take a bit mask parameter that specifies which components to calculate when returning an ''NSDateComponents'' object. The bit mask is composed of ''Unit'' constants (see 'Constants'). In a calendar, day, week, weekday, month, and year numbers are generally 1-based, but there may be calendar-specific exceptions. Ordinal numbers, where they occur, are 1-based. Some calendars represented by this API may have to map their basic unit concepts into year/month/week/day/… nomenclature. For example, a calendar composed of 4 quarters in a year instead of 12 months uses the month unit to represent quarters. The particular values of the unit are defined by each calendar, and are not necessarily consistent with values for that unit in another calendar. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -71,7 +70,6 @@ namespace cocoon std::int64_t component(CalendarUnit unit, const Date& date) const; /** * @brief Calls `-[NSCalendar components:fromDate:]`. - * @details The date components representing a given date. * @param unit_flags Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -79,7 +77,6 @@ namespace cocoon DateComponents components(CalendarUnit unit_flags, const Date& date) const; /** * @brief Calls `-[NSCalendar components:fromDate:toDate:options:]`. - * @details Returns the difference between two supplied dates as date components. The result is lossy if there is not a small enough unit requested to hold the full precision of the difference. Some operations can be ambiguous, and the behavior of the computation is calendar-specific, but generally larger components will be computed before smaller components; for example, in the Gregorian calendar a result might be 1 month and 5 days instead of, for example, 0 months and 35 days. The resulting component values may be negative if 'resultDate' is before 'startDate'. Note that some computations can take a relatively long time. - Parameters: - unitFlags: Specifies the components for the returned 'NSDateComponents' object. - startingDate: The start date for the calculation. - resultDate: The end date for the calculation. - opts: Options for the calculation. If you specify ''NSCalendar/Options/wrapComponents'', the specified components are incremented and wrap around to zero/one on overflow, but do not cause higher units to be incremented. - Returns: An 'NSDateComponents' object whose components are specified by 'unitFlags' and calculated from the difference between the 'resultDate' and 'startDate'. Returns 'nil' if either date falls outside the defined range of the receiver or if the computation cannot be performed. * @param unit_flags Argument converted to the Objective-C parameter of the same role. * @param starting_date Argument converted to the Objective-C parameter of the same role. * @param result_date Argument converted to the Objective-C parameter of the same role. @@ -89,7 +86,7 @@ namespace cocoon DateComponents components(CalendarUnit unit_flags, const Date& starting_date, const Date& result_date, CalendarOptions opts) const; /** * @brief Calls `-[NSCalendar components:fromDateComponents:toDateComponents:options:]`. - * @details Returns the difference between start and end dates given as date components. If an 'NSDateComponents' object does not specify a value for a calendar unit required to determine an absolute date, the base value of that unit is assumed. For example, given an 'NSDateComponents' object with only a 'year' and a 'month' specified, the resulting 'NSDate' object would be constructed using a 'day' value of '1' and 'hour', 'minute', 'second' and 'nanosecond' values of '0'. Passing an 'NSDateComponents' argument with an unspecified 'era' or 'year' value is not advised. If an 'NSDateComponents' object's 'timeZone' property is set, the time zone property value will be used in the calculation. If an 'NSDateComponents' object's 'calendar' property is set, the calendar property value will be used instead of the receiving calendar. If both an 'NSDateComponents' object's 'timeZone' and 'calendar' properties are set, the time zone property value overrides the time zone of the calendar property value. - Parameters: - unitFlags: Specifies the components for the returned 'NSDateComponents' object. - startingDateComp: The start date for the calculation as an 'NSDateComponents' object. - resultDateComp: The end date for the calculation as an 'NSDateComponents' object. - options: The options parameter is currently unused. - Returns: An 'NSDateComponents' object whose components are specified by 'unitFlags' and calculated from the difference between the 'startingDateComp' and 'resultDateComp'. Returns 'nil' if either date falls outside the defined range of the receiver or if the computation cannot be performed. + * @details This API returns the difference between two dates specified as date components. For units which are not specified in each NSDateComponents, but required to specify an absolute date, the base value of the unit is assumed. For example, for an NSDateComponents with just a Year and a Month specified, a Day of 1, and an Hour, Minute, Second, and Nanosecond of 0 are assumed. Calendrical calculations with unspecified Year or Year value prior to the start of a calendar are not advised. For each date components object, if its time zone property is set, that time zone is used for it; if the calendar property is set, that is used rather than the receiving calendar, and if both the calendar and time zone are set, the time zone property value overrides the time zone of the calendar property. No options are currently defined; pass 0. * @param unit_flags Argument converted to the Objective-C parameter of the same role. * @param starting_date_comp Argument converted to the Objective-C parameter of the same role. * @param result_date_comp Argument converted to the Objective-C parameter of the same role. @@ -115,7 +112,6 @@ namespace cocoon bool date(const Date& date, const DateComponents& components) const; /** * @brief Calls `-[NSCalendar dateByAddingComponents:toDate:options:]`. - * @details A date representing the absolute time calculated by adding given components to a given date. * @param comps Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. @@ -145,7 +141,7 @@ namespace cocoon Date date_by_setting_hour(std::int64_t h, std::int64_t m, std::int64_t s, const Date& date, CalendarOptions opts) const; /** * @brief Calls `-[NSCalendar dateBySettingUnit:value:ofDate:options:]`. - * @details Returns a new date representing the date calculated by setting a specific component of a given date to a given value, while trying to keep lower components the same. Changing a component's value often requires higher or coupled components to change as well. For example, setting the 'weekday' to "Thursday" will require the 'day' component to change its value, and possibly the 'month' and 'year' as well. If no such time exists, the next available date is returned, which may be on a different calendar day. - Parameters: - unit: The unit to set with the given value. For possible values, see ''NSCalendar/Unit''. - v: The value to set for the given calendar unit. - date: The date to use to perform the calculation. - opts: Options for the calculation. For possible values, see ''NSCalendar/Options''. - Returns: A new 'NSDate' instance representing the date calculated by setting a specific component of a given date to a given value. If the unit already has that value, this may result in a date which is the same as the given date. + * @details This API returns a new NSDate object representing the date calculated by setting a specific component to a given time, and trying to keep lower components the same. If the unit already has that value, this may result in a date which is the same as the given date. Changing a component's value often will require higher or coupled components to change as well. For example, setting the Weekday to Thursday usually will require the Day component to change its value, and possibly the Month and Year as well. If no such time exists, the next available time is returned (which could, for example, be in a different day, week, month, ... than the nominal target date). Setting a component to something which would be inconsistent forces other units to change; for example, setting the Weekday to Thursday probably shifts the Day and possibly Month and Year. The specific behaviors here are as yet unspecified; for example, if I change the weekday to Thursday, does that move forward to the next, backward to the previous, or to the nearest Thursday? A likely rule is that the algorithm will try to produce a result which is in the next-larger unit to the one given (there's a table of this mapping at the top of this document). So for the "set to Thursday" example, find the Thursday in the Week in which the given date resides (which could be a forwards or backwards move, and not necessarily the nearest Thursday). For forwards or backwards behavior, one can use the -nextDateAfterDate:matchingUnit:value:options: method above. * @param unit Argument converted to the Objective-C parameter of the same role. * @param v Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. @@ -155,7 +151,6 @@ namespace cocoon Date date_by_setting_unit(CalendarUnit unit, std::int64_t v, const Date& date, CalendarOptions opts) const; /** * @brief Calls `-[NSCalendar dateFromComponents:]`. - * @details A date created from the specified components. * @param comps Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -176,7 +171,7 @@ namespace cocoon Date date_with_era(std::int64_t era_value, std::int64_t year_value, std::int64_t month_value, std::int64_t day_value, std::int64_t hour_value, std::int64_t minute_value, std::int64_t second_value, std::int64_t nanosecond_value) const; /** * @brief Calls `-[NSCalendar enumerateDatesStartingAfterDate:matchingComponents:options:usingBlock:]`. - * @details Computes the dates that match (or most closely match) a given set of components, and calls the block once for each of them, until the enumeration is stopped. If you specify a strict matching option (''NSCalendar/Options/matchStrictly''), this method searches as far as necessary looking for a match, up to an implementation-defined limit. If an exact match is not possible, 'nil' is passed to the 'date' argument of the block, and the enumeration is stopped. Otherwise, this method searches as far as the next instance of the next highest calendar unit in the given 'NSDateComponents' object. If you do not specify a strict matching option, you must specify one of ''NSCalendar/Options/matchPreviousTimePreservingSmallerUnits'', ''NSCalendar/Options/matchNextTimePreservingSmallerUnits'', or ''NSCalendar/Options/matchNextTime'', or an illegal argument exception will be thrown. - Parameters: - start: The date for which to perform the calculation. - comps: The date components to match. If no components are specified, the enumeration will not be executed. - opts: Options for the enumeration. For possible values, see ''NSCalendar/Options''. - block: The block to apply to each enumerated date. The block takes three arguments: the enumerated date, whether the date exactly matches the specified date components, and a reference to a Boolean value that the block can set to 'YES' to stop the enumeration. + * @details This method computes the dates which match (or most closely match) a given set of components, and calls the block once for each of them, until the enumeration is stopped. There will be at least one intervening date which does not match all the components (or the given date itself must not match) between the given date and any result. If the NSCalendarSearchBackwards option is used, this method finds the previous match before the given date. The intent is that the same matches as for a forwards search will be found (that is, if you are enumerating forwards or backwards for each hour with minute "27", the seconds in the date you will get in forwards search would obviously be 00, and the same will be true in a backwards search in order to implement this rule. Similarly for DST backwards jumps which repeats times, you'll get the first match by default, where "first" is defined from the point of view of searching forwards. So, when searching backwards looking for a particular hour, with no minute and second specified, you don't get a minute and second of 59:59 for the matching hour (which would be the nominal first match within a given hour, given the other rules here, when searching backwards). If the NSCalendarMatchStrictly option is used, the algorithm travels as far forward or backward as necessary looking for a match, but there are ultimately implementation-defined limits in how far distant the search will go. If the NSCalendarMatchStrictly option is not specified, the algorithm searches up to the end of the next instance of the next higher unit to the highest specified unit in the NSDateComponents argument. If you want to find the next Feb 29 in the Gregorian calendar, for example, you have to specify the NSCalendarMatchStrictly option to guarantee finding it. If an exact match is not possible, and requested with the NSCalendarMatchStrictly option, nil is passed to the block and the enumeration ends. (Logically, since an exact match searches indefinitely into the future, if no match is found there's no point in continuing the enumeration.) If the NSCalendarMatchStrictly option is NOT used, exactly one option from the set {NSCalendarMatchPreviousTimePreservingSmallerUnits, NSCalendarMatchNextTimePreservingSmallerUnits, NSCalendarMatchNextTime} must be specified, or an illegal argument exception will be thrown. If the NSCalendarMatchPreviousTimePreservingSmallerUnits option is specified, and there is no matching time before the end of the next instance of the next higher unit to the highest specified unit in the NSDateComponents argument, the method will return the previous existing value of the missing unit and preserves the lower units' values (e.g., no 2:37am results in 1:37am, if that exists). If the NSCalendarMatchNextTimePreservingSmallerUnits option is specified, and there is no matching time before the end of the next instance of the next higher unit to the highest specified unit in the NSDateComponents argument, the method will return the next existing value of the missing unit and preserves the lower units' values (e.g., no 2:37am results in 3:37am, if that exists). If the NSCalendarMatchNextTime option is specified, and there is no matching time before the end of the next instance of the next higher unit to the highest specified unit in the NSDateComponents argument, the method will return the next existing time which exists (e.g., no 2:37am results in 3:00am, if that exists). If the NSCalendarMatchFirst option is specified, and there are two or more matching times (all the components are the same, including isLeapMonth) before the end of the next instance of the next higher unit to the highest specified unit in the NSDateComponents argument, the method will return the first occurrence. If the NSCalendarMatchLast option is specified, and there are two or more matching times (all the components are the same, including isLeapMonth) before the end of the next instance of the next higher unit to the highest specified unit in the NSDateComponents argument, the method will return the last occurrence. If neither the NSCalendarMatchFirst or NSCalendarMatchLast option is specified, the default behavior is to act as if NSCalendarMatchFirst was specified. There is no option to return middle occurrences of more than two occurrences of a matching time, if such exist. Result dates have an integer number of seconds (as if 0 was specified for the nanoseconds property of the NSDateComponents matching parameter), unless a value was set in the nanoseconds property, in which case the result date will have that number of nanoseconds (or as close as possible with floating point numbers). The enumeration is stopped by setting stop = YES in the block and return. It is not necessary to set stop to NO to keep the enumeration going. * @param start Argument converted to the Objective-C parameter of the same role. * @param comps Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. @@ -185,7 +180,7 @@ namespace cocoon void enumerate_dates_starting_after_date(const Date& start, const DateComponents& comps, CalendarOptions opts, std::function block) const; /** * @brief Calls `-[NSCalendar getEra:year:month:day:fromDate:]`. - * @details Returns the era, year, month, and day of a given date. Pass 'NULL' for a 'NSInteger' pointer parameter if you don't care about that value. + * @details This API is a convenience for getting era, year, month, and day of a given date. Pass NULL for a NSInteger pointer parameter if you don't care about that value. * @param era_value_pointer Argument converted to the Objective-C parameter of the same role. * @param year_value_pointer Argument converted to the Objective-C parameter of the same role. * @param month_value_pointer Argument converted to the Objective-C parameter of the same role. @@ -195,7 +190,7 @@ namespace cocoon void get_era(std::int64_t* era_value_pointer, std::int64_t* year_value_pointer, std::int64_t* month_value_pointer, std::int64_t* day_value_pointer, const Date& date) const; /** * @brief Calls `-[NSCalendar getHour:minute:second:nanosecond:fromDate:]`. - * @details Returns the hour, minute, second, and nanoseconds of a given date. Pass 'NULL' for a 'NSInteger' pointer parameter if you don't care about that value. + * @details This API is a convenience for getting hour, minute, second, and nanoseconds of a given date. Pass NULL for a NSInteger pointer parameter if you don't care about that value. * @param hour_value_pointer Argument converted to the Objective-C parameter of the same role. * @param minute_value_pointer Argument converted to the Objective-C parameter of the same role. * @param second_value_pointer Argument converted to the Objective-C parameter of the same role. @@ -250,14 +245,12 @@ namespace cocoon bool is_date_in_yesterday(const Date& date) const; /** * @brief Calls `-[NSCalendar maximumRangeOfUnit:]`. - * @details The maximum range limits of the values that a given unit can take on. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Range maximum_range_of_unit(CalendarUnit unit) const; /** * @brief Calls `-[NSCalendar minimumRangeOfUnit:]`. - * @details The minimum range limits of the values that a given unit can take on. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -294,7 +287,7 @@ namespace cocoon Date next_date_after_date(const Date& date, CalendarUnit unit, std::int64_t value, CalendarOptions options) const; /** * @brief Calls `-[NSCalendar nextWeekendStartDate:interval:options:afterDate:]`. - * @details Returns by reference the starting date and time interval range of the next weekend period after a given date. Note that a particular calendar day may not necessarily fall entirely within a weekend period, as weekends can start in the middle of a day in some calendars and locales. The 'NSCalendarSearchBackwards' option can be used to find the previous weekend range strictly before the date. Returns 'NO' if there are no such things as weekends in the calendar and its locale. - Parameters: - datep: Upon return, contains the starting date of the next weekend period. - tip: Upon return, contains the time interval of the next weekend period. - options: Options for the calculation. If you specify ''NSCalendar/Options/searchBackwards'', the starting date and time interval range of the preceding weekend period will be returned by reference instead. - date: The date for which to perform the calculation. - Returns: 'NO' if the calendar and locale do not have the concept of a weekend, otherwise 'YES'. + * @details Returns the range of the next weekend, via two by-reference parameters, which starts strictly after the given date. The NSCalendarSearchBackwards option can be used to find the previous weekend range strictly before the date. Returns NO if there are no such things as weekend in the calendar and its locale. Note that a given entire Day within a calendar is not necessarily all in a weekend or not; weekends can start in the middle of a Day in some calendars and locales. * @param datep Argument converted to the Objective-C parameter of the same role. * @param tip Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. @@ -304,7 +297,6 @@ namespace cocoon bool next_weekend_start_date(Date& datep, double* tip, CalendarOptions options, const Date& date) const; /** * @brief Calls `-[NSCalendar ordinalityOfUnit:inUnit:forDate:]`. - * @details The ordinal number of a smaller calendar unit within a specified larger calendar unit for a specified absolute time. * @param smaller Argument converted to the Objective-C parameter of the same role. * @param larger Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. @@ -313,7 +305,6 @@ namespace cocoon std::uint64_t ordinality_of_unit(CalendarUnit smaller, CalendarUnit larger, const Date& date) const; /** * @brief Calls `-[NSCalendar rangeOfUnit:inUnit:forDate:]`. - * @details The range of absolute time values that a smaller calendar unit can take on in a larger calendar unit for a specified absolute time. * @param smaller Argument converted to the Objective-C parameter of the same role. * @param larger Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. @@ -322,7 +313,6 @@ namespace cocoon Range range_of_unit(CalendarUnit smaller, CalendarUnit larger, const Date& date) const; /** * @brief Calls `-[NSCalendar rangeOfUnit:startDate:interval:forDate:]`. - * @details The starting time and duration of a given calendar unit that contains a given date. * @param unit Argument converted to the Objective-C parameter of the same role. * @param datep Argument converted to the Objective-C parameter of the same role. * @param tip Argument converted to the Objective-C parameter of the same role. @@ -332,7 +322,7 @@ namespace cocoon bool range_of_unit(CalendarUnit unit, Date& datep, double* tip, const Date& date) const; /** * @brief Calls `-[NSCalendar rangeOfWeekendStartDate:interval:containingDate:]`. - * @details Returns whether a given date falls within a weekend period, and if so, returns by reference the start date and time interval of the weekend range. Note that a particular calendar day may not necessarily fall entirely within a weekend period, as weekends can start in the middle of a day in some calendars and locales. - Parameters: - datep: Upon return, contains the starting date of the weekend period. - tip: Upon return, contains the time interval of the weekend period. - date: The date to use to perform the calculation. - Returns: 'YES' if the given date falls within a weekend period, otherwise 'NO'. + * @details Find the range of the weekend around the given date, returned via two by-reference parameters. Returns NO if the given date is not in a weekend. Note that a given entire Day within a calendar is not necessarily all in a weekend or not; weekends can start in the middle of a Day in some calendars and locales. * @param datep Argument converted to the Objective-C parameter of the same role. * @param tip Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. @@ -348,187 +338,156 @@ namespace cocoon Date start_of_day_for_date(const Date& date) const; /** * @brief Returns the `AMSymbol` property of `NSCalendar`. - * @details The AM symbol for this calendar. * @return The converted Objective-C result. */ std::string am_symbol() const; /** * @brief Returns the `PMSymbol` property of `NSCalendar`. - * @details The PM symbol for this calendar. * @return The converted Objective-C result. */ std::string pm_symbol() const; /** * @brief Returns the `autoupdatingCurrentCalendar` property of `NSCalendar`. - * @details A calendar that tracks changes to user's preferred calendar. Settings you get from this calendar do change as the user's settings change. Note that if you cache values based on the calendar or related information those caches will of course not be automatically updated by the updating of the calendar object. * @return The converted Objective-C result. */ static Calendar autoupdating_current_calendar(); /** * @brief Returns the `calendarIdentifier` property of `NSCalendar`. - * @details An identifier for the calendar. * @return The converted Objective-C result. */ std::string calendar_identifier() const; /** * @brief Returns the `currentCalendar` property of `NSCalendar`. - * @details The user's current calendar. The returned calendar is formed from the settings for the current user's chosen system locale overlaid with any custom settings the user has specified in System Preferences. Settings you get from this calendar do not change as System Preferences are changed. * @return The converted Objective-C result. */ static Calendar current_calendar(); /** * @brief Returns the `eraSymbols` property of `NSCalendar`. - * @details A list of era symbols for this calendar. * @return The converted Objective-C result. */ std::vector era_symbols() const; /** * @brief Returns the `firstWeekday` property of `NSCalendar`. - * @details The index of the first weekday for the calendar. * @return The converted Objective-C result. */ std::uint64_t first_weekday() const; /** * @brief Sets the `firstWeekday` property of `NSCalendar`. - * @details The index of the first weekday for the calendar. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_first_weekday(std::uint64_t value) const; /** * @brief Returns the `locale` property of `NSCalendar`. - * @details The locale for the calendar. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSCalendar`. - * @details The locale for the calendar. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; /** * @brief Returns the `longEraSymbols` property of `NSCalendar`. - * @details The long era symbols for this calendar. * @return The converted Objective-C result. */ std::vector long_era_symbols() const; /** * @brief Returns the `minimumDaysInFirstWeek` property of `NSCalendar`. - * @details The minimum number of days in the first week of the calendar. * @return The converted Objective-C result. */ std::uint64_t minimum_days_in_first_week() const; /** * @brief Sets the `minimumDaysInFirstWeek` property of `NSCalendar`. - * @details The minimum number of days in the first week of the calendar. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minimum_days_in_first_week(std::uint64_t value) const; /** * @brief Returns the `monthSymbols` property of `NSCalendar`. - * @details The list of month symbols for this calendar. * @return The converted Objective-C result. */ std::vector month_symbols() const; /** * @brief Returns the `quarterSymbols` property of `NSCalendar`. - * @details The list of quarter symbols for this calendar. * @return The converted Objective-C result. */ std::vector quarter_symbols() const; /** * @brief Returns the `shortMonthSymbols` property of `NSCalendar`. - * @details The list of short month symbols for this calendar. * @return The converted Objective-C result. */ std::vector short_month_symbols() const; /** * @brief Returns the `shortQuarterSymbols` property of `NSCalendar`. - * @details The list of short quarter symbols for this calendar. * @return The converted Objective-C result. */ std::vector short_quarter_symbols() const; /** * @brief Returns the `shortStandaloneMonthSymbols` property of `NSCalendar`. - * @details The list of short standalone month symbols for this calendar. * @return The converted Objective-C result. */ std::vector short_standalone_month_symbols() const; /** * @brief Returns the `shortStandaloneQuarterSymbols` property of `NSCalendar`. - * @details The list of short standalone quarter symbols for this calendar. * @return The converted Objective-C result. */ std::vector short_standalone_quarter_symbols() const; /** * @brief Returns the `shortStandaloneWeekdaySymbols` property of `NSCalendar`. - * @details The list of short standalone weekday symbols for this calendar. * @return The converted Objective-C result. */ std::vector short_standalone_weekday_symbols() const; /** * @brief Returns the `shortWeekdaySymbols` property of `NSCalendar`. - * @details The list of short weekday symbols for this calendar. * @return The converted Objective-C result. */ std::vector short_weekday_symbols() const; /** * @brief Returns the `standaloneMonthSymbols` property of `NSCalendar`. - * @details The list of standalone month symbols for this calendar. * @return The converted Objective-C result. */ std::vector standalone_month_symbols() const; /** * @brief Returns the `standaloneQuarterSymbols` property of `NSCalendar`. - * @details The list of standalone quarter symbols for this calendar. * @return The converted Objective-C result. */ std::vector standalone_quarter_symbols() const; /** * @brief Returns the `standaloneWeekdaySymbols` property of `NSCalendar`. - * @details The list of standalone weekday symbols for this calendar. * @return The converted Objective-C result. */ std::vector standalone_weekday_symbols() const; /** * @brief Returns the `timeZone` property of `NSCalendar`. - * @details The time zone for the calendar. * @return The converted Objective-C result. */ TimeZone time_zone() const; /** * @brief Sets the `timeZone` property of `NSCalendar`. - * @details The time zone for the calendar. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_time_zone(const TimeZone& value) const; /** * @brief Returns the `veryShortMonthSymbols` property of `NSCalendar`. - * @details The list of very short month symbols for this calendar. * @return The converted Objective-C result. */ std::vector very_short_month_symbols() const; /** * @brief Returns the `veryShortStandaloneMonthSymbols` property of `NSCalendar`. - * @details The list of very short standalone month symbols for this calendar. * @return The converted Objective-C result. */ std::vector very_short_standalone_month_symbols() const; /** * @brief Returns the `veryShortStandaloneWeekdaySymbols` property of `NSCalendar`. - * @details The list of very short standalone weekday symbols for this calendar. * @return The converted Objective-C result. */ std::vector very_short_standalone_weekday_symbols() const; /** * @brief Returns the `veryShortWeekdaySymbols` property of `NSCalendar`. - * @details The list of very short weekday symbols for this calendar. * @return The converted Objective-C result. */ std::vector very_short_weekday_symbols() const; /** * @brief Returns the `weekdaySymbols` property of `NSCalendar`. - * @details The list of weekday symbols for this calendar. * @return The converted Objective-C result. */ std::vector weekday_symbols() const; diff --git a/include/generated/calendar_date.h b/include/generated/calendar_date.h index dd429425..f281ff6f 100644 --- a/include/generated/calendar_date.h +++ b/include/generated/calendar_date.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSCalendarDate` (Foundation). - * @details A specialized date object with embedded calendar information. \@DeprecationSummary { Use ''NSDate'' and ''NSCalendar'' instead. } * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Date. * diff --git a/include/generated/character_set.h b/include/generated/character_set.h index f839e8e0..ada21a8b 100644 --- a/include/generated/character_set.h +++ b/include/generated/character_set.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSCharacterSet` (Foundation). - * @details An object representing a fixed set of Unicode character values for use in search operations. In Swift, this bridges to a ''CharacterSet''; use ''NSCharacterSet'' when you need reference semantics or other Foundation-specific behavior. An 'NSCharacterSet' object represents a set of Unicode-compliant characters. 'NSString' and 'NSScanner' objects use 'NSCharacterSet' objects to group characters together for searching operations, so that they can find any of a particular set of characters during a search. The cluster's two public classes, 'NSCharacterSet' and ''NSMutableCharacterSet'', declare the programmatic interface for static and dynamic character sets, respectively. The objects you create using these classes are referred to as character set objects (and when no confusion will result, merely as character sets). Because of the nature of class clusters, character set objects aren't actual instances of the 'NSCharacterSet' or 'NSMutableCharacterSet' classes but of one of their private subclasses. Although a character set object's class is private, its interface is public, as declared by these abstract superclasses, 'NSCharacterSet' and 'NSMutableCharacterSet'. The character set classes adopt the 'NSCopying' and 'NSMutableCopying' protocols, making it convenient to convert a character set of one type to the other. The 'NSCharacterSet' class declares the programmatic interface for an object that manages a set of Unicode characters (see the ''NSString'' class cluster specification for information on Unicode). 'NSCharacterSet''s principal primitive method, ''characterIsMember(:)'', provides the basis for all other instance methods in its interface. A subclass of 'NSCharacterSet' needs only to implement this method, plus ''NSMutableCopying/mutableCopy(with:)'', for proper behavior. For optimal performance, a subclass should also override ''bitmapRepresentation'', which otherwise works by invoking ''characterIsMember(:)'' for every possible Unicode value. 'NSCharacterSet' is "toll-free bridged" with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. > Important: > The Swift overlay to the Foundation framework provides the ''CharacterSet'' structure, which bridges to the ''NSCharacterSet'' class and its mutable subclass, ''NSMutableCharacterSet''. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,28 +46,24 @@ namespace cocoon explicit CharacterSet(Adopt adopt); /** * @brief Calls `-[NSCharacterSet characterIsMember:]`. - * @details Returns a Boolean value that indicates whether a given character is in the receiver. - Parameter aCharacter: The character to test for membership of the receiver. - Returns: 'YES' if 'aCharacter' is in the receiving character set, otherwise 'NO'. * @param a_character Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool character_is_member(std::uint16_t a_character) const; /** * @brief Calls `-[NSCharacterSet hasMemberInPlane:]`. - * @details Returns a Boolean value that indicates whether the receiver has at least one member in a given character plane. This method makes it easier to find the plane containing the members of the current character set. The Basic Multilingual Plane (BMP) is plane '0'. - Parameter thePlane: A character plane. - Returns: 'YES' if the receiver has at least one member in 'thePlane', otherwise 'NO'. * @param the_plane Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool has_member_in_plane(std::uint8_t the_plane) const; /** * @brief Calls `-[NSCharacterSet isSupersetOfSet:]`. - * @details Returns a Boolean value that indicates whether the receiver is a superset of another given character set. - Parameter theOtherSet: A character set. - Returns: 'YES' if the receiver is a superset of 'theOtherSet', otherwise 'NO'. * @param the_other_set Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_superset_of_set(const CharacterSet& the_other_set) const; /** * @brief Calls `-[NSCharacterSet longCharacterIsMember:]`. - * @details Returns a Boolean value that indicates whether a given long character is a member of the receiver. This method supports the specification of 32-bit characters. - Parameter theLongChar: A UTF32 character. - Returns: 'YES' if 'theLongChar' is in the receiver, otherwise 'NO'. * @param the_long_char Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -105,103 +100,86 @@ namespace cocoon static CharacterSet url_user_allowed_character_set(); /** * @brief Returns the `alphanumericCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Categories L\\, M\\, and N\\. Informally, this set is the set of all characters used as basic units of alphabets, syllabaries, ideographs, and digits. * @return The converted Objective-C result. */ static CharacterSet alphanumeric_character_set(); /** * @brief Returns the `bitmapRepresentation` property of `NSCharacterSet`. - * @details An 'NSData' object encoding the receiver in binary format. This format is suitable for saving to a file or otherwise transmitting or archiving. A raw bitmap representation of a character set is a byte array with the first 2^16 bits (that is, 8192 bytes) representing the code point range of the Basic Multilingual Plane (BMP), such that the value of the bit at position n represents the presence in the character set of the character with decimal Unicode value n. A bitmap representation may contain zero to sixteen additional 8192 byte segments for each additional Unicode plane containing a character in a character set, with each 8192 byte segment prepended with a single plane index byte. For example, a character set containing only Basic Latin (ASCII) characters, which are contained by the Basic Multilingual Plane (BMP, plane 0), has a bitmap representation with a size of 8192 bytes, whereas a character set containing both Basic Latin (ASCII) characters and emoji characters, which are contained by the Supplementary Multilingual Plane (SMP, plane 1), has a bitmap representation with a size of 16385 bytes (8192 bytes for BMP, followed by the byte '0x01' for the plane index of SMP, followed by 8192 bytes for SMP). To test for the presence of a character in the Basic Multilingual Plane (BMP) with decimal Unicode value n in a raw bitmap representation, you might do the following: '''objc unsigned char bitmapRep[8192]; if (bitmapRep[n >> 3] & (((unsigned int)1) \<\< (n & 7))) { / Character is present. } ''' * @return The converted Objective-C result. */ std::vector bitmap_representation() const; /** * @brief Returns the `capitalizedLetterCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category Lt. * @return The converted Objective-C result. */ static CharacterSet capitalized_letter_character_set(); /** * @brief Returns the `controlCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category Cc and Cf. These characters include, for example, the soft hyphen ('U+00AD'), control characters to support bi-directional text, and IETF language tag characters. * @return The converted Objective-C result. */ static CharacterSet control_character_set(); /** * @brief Returns the `decimalDigitCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in the category of Decimal Numbers. Informally, this set is the set of all characters used to represent the decimal values '0' through '9'. These characters include, for example, the decimal digits of the Indic scripts and Arabic. * @return The converted Objective-C result. */ static CharacterSet decimal_digit_character_set(); /** * @brief Returns the `decomposableCharacterSet` property of `NSCharacterSet`. - * @details A character set containing individual Unicode characters that can also be represented as composed character sequences (such as for letters with accents), by the definition of "standard decomposition" in version 3.2 of the Unicode character encoding standard. These characters include compatibility characters as well as pre-composed characters. > Note: This character set doesn't currently include the Hangul characters defined in version 2.0 of the Unicode standard. * @return The converted Objective-C result. */ static CharacterSet decomposable_character_set(); /** * @brief Returns the `illegalCharacterSet` property of `NSCharacterSet`. - * @details A character set containing values in the category of Non-Characters or that have not yet been defined in version 3.2 of the Unicode standard. * @return The converted Objective-C result. */ static CharacterSet illegal_character_set(); /** * @brief Returns the `invertedSet` property of `NSCharacterSet`. - * @details A character set containing only characters that don't exist in the receiver. Using the inverse of an immutable character set is much more efficient than inverting a mutable character set. * @return The converted Objective-C result. */ CharacterSet inverted_set() const; /** * @brief Returns the `letterCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category L\\ & M\\. Informally, this set is the set of all characters used as letters of alphabets and ideographs. * @return The converted Objective-C result. */ static CharacterSet letter_character_set(); /** * @brief Returns the `lowercaseLetterCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category Ll. Informally, this set is the set of all characters used as lowercase letters in alphabets that make case distinctions. * @return The converted Objective-C result. */ static CharacterSet lowercase_letter_character_set(); /** * @brief Returns the `newlineCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the newline characters ('U+000A' ~ 'U+000D', 'U+0085', 'U+2028', and 'U+2029'). * @return The converted Objective-C result. */ static CharacterSet newline_character_set(); /** * @brief Returns the `nonBaseCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category M\\. This set is also defined as all legal Unicode characters with a non-spacing priority greater than '0'. Informally, this set is the set of all characters used as modifiers of base characters. * @return The converted Objective-C result. */ static CharacterSet non_base_character_set(); /** * @brief Returns the `punctuationCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category P\\. Informally, this set is the set of all non-whitespace characters used to separate linguistic units in scripts, such as periods, dashes, parentheses, and so on. * @return The converted Objective-C result. */ static CharacterSet punctuation_character_set(); /** * @brief Returns the `symbolCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category S\\. These characters include, for example, the dollar sign ('$') and the plus ('+') sign. * @return The converted Objective-C result. */ static CharacterSet symbol_character_set(); /** * @brief Returns the `uppercaseLetterCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category Lu and Lt. Informally, this set is the set of all characters used as uppercase letters in alphabets that make case distinctions. * @return The converted Objective-C result. */ static CharacterSet uppercase_letter_character_set(); /** * @brief Returns the `whitespaceAndNewlineCharacterSet` property of `NSCharacterSet`. - * @details A character set containing characters in Unicode General Category Z\\, 'U+000A' ~ 'U+000D', and 'U+0085'. * @return The converted Objective-C result. */ static CharacterSet whitespace_and_newline_character_set(); /** * @brief Returns the `whitespaceCharacterSet` property of `NSCharacterSet`. - * @details A character set containing the characters in Unicode General Category Zs and 'CHARACTER TABULATION' ('U+0009'). This set doesn't contain the newline or carriage return characters. * @return The converted Objective-C result. */ static CharacterSet whitespace_character_set(); diff --git a/include/generated/class_description.h b/include/generated/class_description.h index 33ccbe3c..a6de3e5f 100644 --- a/include/generated/class_description.h +++ b/include/generated/class_description.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSClassDescription` (Foundation). - * @details An abstract class that provides the interface for querying the relationships and properties of a class. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -40,45 +39,38 @@ namespace cocoon explicit ClassDescription(Adopt adopt); /** * @brief Calls `+[NSClassDescription classDescriptionForClass:]`. - * @details Returns the class description for a given class. * @param a_class Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static ClassDescription class_description_for_class(const std::string& a_class); /** * @brief Calls `+[NSClassDescription invalidateClassDescriptionCache]`. - * @details Removes all ''NSClassDescription'' objects from the cache. */ static void invalidate_class_description_cache(); /** * @brief Calls `-[NSClassDescription inverseForRelationshipKey:]`. - * @details Returns the name of the inverse relationship from a relationship specified by a given key. * @param relationship_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string inverse_for_relationship_key(const std::string& relationship_key) const; /** * @brief Calls `+[NSClassDescription registerClassDescription:forClass:]`. - * @details Registers an ''NSClassDescription'' object for a given class in the ''NSClassDescription'' cache. * @param description Argument converted to the Objective-C parameter of the same role. * @param a_class Argument converted to the Objective-C parameter of the same role. */ static void register_class_description(const ClassDescription& description, const std::string& a_class); /** * @brief Returns the `attributeKeys` property of `NSClassDescription`. - * @details An array of ''NSString'' objects representing the receiver's attribute keys. * @return The converted Objective-C result. */ std::vector attribute_keys() const; /** * @brief Returns the `toManyRelationshipKeys` property of `NSClassDescription`. - * @details An array of ''NSString'' objects representing the keys for the receiver's to-many relationships. * @return The converted Objective-C result. */ std::vector to_many_relationship_keys() const; /** * @brief Returns the `toOneRelationshipKeys` property of `NSClassDescription`. - * @details An array of ''NSString'' objects representing the keys for the receiver's to-one relationships. * @return The converted Objective-C result. */ std::vector to_one_relationship_keys() const; diff --git a/include/generated/clone_command.h b/include/generated/clone_command.h index fac485c6..3f737629 100644 --- a/include/generated/clone_command.h +++ b/include/generated/clone_command.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCloneCommand` (Foundation). - * @details A command that clones one or more scriptable objects. An instance of 'NSCloneCommand' clones the specified scriptable object or objects (such as words, paragraphs, images, and so on) and inserts them in the specified location, or the default location if no location is specified. The cloned scriptable objects typically correspond to objects in the application, but aren't required to. This command corresponds to AppleScript's 'duplicate' command. 'NSCloneCommand' is part of Cocoa's built-in scripting support. It works automatically to support the 'duplicate' command through key-value coding. Most applications don't need to subclass 'NSCloneCommand' or invoke its methods. When an instance of 'NSCloneCommand' is executed, it clones the specified objects by sending them \ messages. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptCommand. * @@ -43,13 +42,11 @@ namespace cocoon using ScriptCommand::set_receivers_specifier; /** * @brief Calls `-[NSCloneCommand setReceiversSpecifier:]`. - * @details Splits off the inner-most child specifier from the receivers specifier. * @param receivers_ref Argument converted to the Objective-C parameter of the same role. */ void set_receivers_specifier(const ScriptObjectSpecifier& receivers_ref) const; /** * @brief Returns the `keySpecifier` property of `NSCloneCommand`. - * @details The key specifier for the clone operation. * @return The converted Objective-C result. */ ScriptObjectSpecifier key_specifier() const; diff --git a/include/generated/close_command.h b/include/generated/close_command.h index 8fba4498..30e66f41 100644 --- a/include/generated/close_command.h +++ b/include/generated/close_command.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSCloseCommand` (Foundation). - * @details A command that closes one or more scriptable objects. An instance of 'NSCloseCommand' closes the specified scriptable object or objects—typically a document or window (and its associated document, if any). The command may optionally specify a location to save in and how to handle modified documents (by automatically saving changes, not saving them, or asking the user). 'NSCloseCommand' is part of Cocoa's built-in scripting support. It works automatically to support the 'close' command through key-value coding. Most applications don't need to subclass 'NSCloseCommand' or call its methods. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptCommand. * @@ -33,7 +32,6 @@ namespace cocoon explicit CloseCommand(Adopt adopt); /** * @brief Returns the `saveOptions` property of `NSCloseCommand`. - * @details The save options specified by the command. * @return The converted Objective-C result. */ SaveOptions save_options() const; diff --git a/include/generated/coder.h b/include/generated/coder.h index 8af786c4..29c3f3e2 100644 --- a/include/generated/coder.h +++ b/include/generated/coder.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCoder` (Foundation). - * @details An abstract class that serves as the basis for objects that enable archiving and distribution of other objects. ''NSCoder'' declares the interface used by concrete subclasses to transfer objects and other values between memory and some other format. This capability provides the basis for archiving (storing objects and data on disk) and distribution (copying objects and data items between different processes or threads). The concrete subclasses provided by Foundation for these purposes are ''NSArchiver'', ''NSUnarchiver'', ''NSKeyedArchiver'', ''NSKeyedUnarchiver'', and ''NSPortCoder''. Concrete subclasses of ''NSCoder'' are "coder classes", and instances of these classes are "coder objects" (or simply "coders"). A coder that can only encode values is an "encoder", and one that can only decode values is a "decoder". ''NSCoder'' operates on objects, scalars, C arrays, structures, strings, and on pointers to these types. It doesn't handle types whose implementation varies across platforms, such as 'union', 'void ', function pointers, and long chains of pointers. A coder stores object type information along with the data, so an object decoded from a stream of bytes is normally of the same class as the object that was originally encoded into the stream. An object can change its class when encoded, however; this is described in [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html\#//apple_ref/doc/uid/10000047i). The AVFoundation framework adds methods to the ''NSCoder'' class to make it easier to create archives including Core Media time structures, and extract Core Media time structure from archives. \#\#\# Subclassing Notes For details of how to create a subclass of 'NSCoder', see [Subclassing NSCoder](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Articles/subclassing.html\#//apple_ref/doc/uid/20000951) in [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html\#//apple_ref/doc/uid/10000047i). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -43,14 +42,12 @@ namespace cocoon explicit Coder(Adopt adopt); /** * @brief Calls `-[NSCoder containsValueForKey:]`. - * @details Returns a Boolean value that indicates whether an encoded value is available for a string. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool contains_value_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeArrayOfObjCType:count:at:]`. - * @details Decodes an array of 'count' items, whose Objective-C type is given by 'itemType'. The items are decoded into the buffer beginning at 'array', which must be large enough to contain them all. 'itemType' must contain exactly one type code. This method matches an ''encodeArrayOfObjCType:count:at:'' message used during encoding. You should not use this method to decode C arrays of Objective-C objects. * @param item_type Argument converted to the Objective-C parameter of the same role. * @param count Argument converted to the Objective-C parameter of the same role. * @param array Argument converted to the Objective-C parameter of the same role. @@ -74,7 +71,6 @@ namespace cocoon std::vector decode_array_of_objects_of_classes(const std::vector& classes, const std::string& key) const; /** * @brief Calls `-[NSCoder decodeBoolForKey:]`. - * @details Decodes and returns a boolean value that was previously encoded and associated with the string 'key'. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -89,7 +85,6 @@ namespace cocoon const std::uint8_t* decode_bytes_for_key(const std::string& key, std::uint64_t length) const; /** * @brief Calls `-[NSCoder decodeBytesForKey:returnedLength:]`. - * @details Decodes a buffer of data that was previously encoded with ''encodeBytes:length:forKey:'' and associated with the string 'key'. The buffer's length is returned by reference in 'lengthp'. The returned bytes are immutable. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @param lengthp Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -104,14 +99,12 @@ namespace cocoon void* decode_bytes_with_minimum_length(std::uint64_t length) const; /** * @brief Calls `-[NSCoder decodeBytesWithReturnedLength:]`. - * @details Decodes a buffer of data whose types are unspecified. The buffer's length is returned by reference in 'lengthp'. If you need the bytes beyond the scope of the current '\@autoreleasepool' block, you must copy them. This method matches an ''encodeBytes:length:'' message used during encoding. * @param lengthp Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ void* decode_bytes_with_returned_length(std::uint64_t* lengthp) const; /** * @brief Calls `-[NSCoder decodeDataObject]`. - * @details Decodes and returns an 'NSData' object that was previously encoded with ''encodeDataObject:''. Subclasses must override this method. * @return The converted Objective-C result. */ std::vector decode_data_object() const; @@ -135,55 +128,47 @@ namespace cocoon std::vector> decode_dictionary_with_keys_of_classes(const std::vector& key_classes, const std::vector& object_classes, const std::string& key) const; /** * @brief Calls `-[NSCoder decodeDoubleForKey:]`. - * @details Decodes and returns a double value that was previously encoded and associated with the string 'key'. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double decode_double_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeFloatForKey:]`. - * @details Decodes and returns a float value that was previously encoded and associated with the string 'key'. If the value was encoded as a double, the extra precision is lost. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ float decode_float_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeInt32ForKey:]`. - * @details Decodes and returns a 32-bit integer value that was previously encoded and associated with the string 'key'. If the encoded integer does not fit into a 32-bit integer, the method raises an 'NSRangeException'. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ int decode_int32_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeInt64ForKey:]`. - * @details Decodes and returns a 64-bit integer value that was previously encoded and associated with the string 'key'. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::int64_t decode_int64_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeIntForKey:]`. - * @details Decodes and returns an int value that was previously encoded and associated with the string 'key'. If the encoded integer does not fit into the default integer size, the method raises an 'NSRangeException'. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ int decode_int_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeIntegerForKey:]`. - * @details Decodes and returns an NSInteger value that was previously encoded and associated with the string 'key'. If the encoded integer does not fit into the NSInteger size, the method raises an 'NSRangeException'. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::int64_t decode_integer_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeObject]`. - * @details Decodes and returns a previously-encoded object. 'NSCoder''s implementation invokes ''decodeValueOfObjCType:at:size:'' to decode the object data. Subclasses may need to override this method if they override any of the corresponding 'encode...Object' methods. * @return The converted Objective-C result. */ Object decode_object() const; /** * @brief Calls `-[NSCoder decodeObjectForKey:]`. - * @details Decodes and returns a previously-encoded object that was associated with the string 'key'. Subclasses must override this method if they perform keyed coding. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -215,7 +200,6 @@ namespace cocoon Point decode_point_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodePropertyList]`. - * @details Decodes a property list that was previously encoded with ''encodePropertyList:''. * @return The converted Objective-C result. */ Object decode_property_list() const; @@ -249,20 +233,17 @@ namespace cocoon Size decode_size_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeTopLevelObjectAndReturnError:]`. - * @details Decodes a previously-encoded object, returning an error if decoding fails. * @return The converted Objective-C result. */ Object decode_top_level_object_and_return_error() const; /** * @brief Calls `-[NSCoder decodeTopLevelObjectForKey:error:]`. - * @details Decodes and returns a previously-encoded object for the given key, returning an error if decoding fails. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object decode_top_level_object_for_key(const std::string& key) const; /** * @brief Calls `-[NSCoder decodeTopLevelObjectOfClass:forKey:error:]`. - * @details Decodes an object for the key and restricted class, returning an error if decoding fails. * @param a_class Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -270,7 +251,6 @@ namespace cocoon Object decode_top_level_object_of_class(const std::string& a_class, const std::string& key) const; /** * @brief Calls `-[NSCoder decodeTopLevelObjectOfClasses:forKey:error:]`. - * @details Decodes an object for the key and restricted classes, returning an error if decoding fails. * @param classes Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -278,14 +258,13 @@ namespace cocoon Object decode_top_level_object_of_classes(const std::vector& classes, const std::string& key) const; /** * @brief Calls `-[NSCoder decodeValueOfObjCType:at:]`. - * @details Decodes a single value, whose Objective-C type is given by 'type'. \@DeprecationSummary { Use ''decodeValueOfObjCType:at:size:'' instead. } This method is unsafe because it could potentially cause buffer overruns. + * @details This method is unsafe because it could potentially cause buffer overruns. You should use -decodeValueOfObjCType:at:size: instead. * @param type Argument converted to the Objective-C parameter of the same role. * @param data Argument converted to the Objective-C parameter of the same role. */ void decode_value_of_obj_c_type(const std::string& type, void* data) const; /** * @brief Calls `-[NSCoder decodeValueOfObjCType:at:size:]`. - * @details Decodes a single value of a known type from the specified data buffer. The 'type' parameter must contain exactly one type code, and the buffer specified by 'data' must be large enough to hold the value corresponding to that type code. Subclasses must override this method and provide an implementation to decode the value. This method matches an ''encodeValueOfObjCType:at:'' message used during encoding. * @param type Argument converted to the Objective-C parameter of the same role. * @param data Argument converted to the Objective-C parameter of the same role. * @param size Argument converted to the Objective-C parameter of the same role. @@ -293,7 +272,6 @@ namespace cocoon void decode_value_of_obj_c_type(const std::string& type, void* data, std::uint64_t size) const; /** * @brief Calls `-[NSCoder encodeArrayOfObjCType:count:at:]`. - * @details Encodes an array of the given Objective-C type, provided the number of items and a pointer. The values are encoded from the buffer beginning at 'array'. 'type' must contain exactly one type code. This method must be matched by a subsequent ''decodeArrayOfObjCType:count:at:'' message. You should not use this method to encode C arrays of Objective-C objects. * @param type Argument converted to the Objective-C parameter of the same role. * @param count Argument converted to the Objective-C parameter of the same role. * @param array Argument converted to the Objective-C parameter of the same role. @@ -301,33 +279,28 @@ namespace cocoon void encode_array_of_obj_c_type(const std::string& type, std::uint64_t count, const void* array) const; /** * @brief Calls `-[NSCoder encodeBool:forKey:]`. - * @details Encodes a Boolean value and associates it with the string 'key'. Subclasses must override this method if they perform keyed coding. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_bool(bool value, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeBycopyObject:]`. - * @details An encoding method for subclasses to override such that it creates a copy, rather than a proxy, when decoded. 'NSCoder''s implementation simply invokes ''encodeObject:''. This method must be matched by a corresponding ''decodeObject'' message. * @param an_object Argument converted to the Objective-C parameter of the same role. */ void encode_bycopy_object(const Object& an_object) const; /** * @brief Calls `-[NSCoder encodeByrefObject:]`. - * @details An encoding method for subclasses to override such that it creates a proxy, rather than a copy, when decoded. 'NSCoder''s implementation simply invokes ''encodeObject:''. This method must be matched by a corresponding ''decodeObject'' message. * @param an_object Argument converted to the Objective-C parameter of the same role. */ void encode_byref_object(const Object& an_object) const; /** * @brief Calls `-[NSCoder encodeBytes:length:]`. - * @details Encodes a buffer of data of an unspecified type. The buffer to be encoded begins at 'byteaddr', and its length in bytes is given by 'length'. This method must be matched by a corresponding ''decodeBytesWithReturnedLength:'' message. * @param byteaddr Argument converted to the Objective-C parameter of the same role. * @param length Argument converted to the Objective-C parameter of the same role. */ void encode_bytes(const void* byteaddr, std::uint64_t length) const; /** * @brief Calls `-[NSCoder encodeBytes:length:forKey:]`. - * @details Encodes a buffer of data, given its length and a pointer, and associates it with a string key. Subclasses must override this method if they perform keyed coding. * @param bytes Argument converted to the Objective-C parameter of the same role. * @param length Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. @@ -335,74 +308,63 @@ namespace cocoon void encode_bytes(const std::uint8_t* bytes, std::uint64_t length, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeConditionalObject:]`. - * @details An encoding method for subclasses to override to conditionally encode an object, preserving common references to it. In the overriding method, 'object' should be encoded only if it's unconditionally encoded elsewhere (with any other 'encode...Object:' method). 'NSCoder''s implementation simply invokes ''encodeObject:''. This method must be matched by a subsequent ''decodeObject'' message. * @param object Argument converted to the Objective-C parameter of the same role. */ void encode_conditional_object(const Object& object) const; /** * @brief Calls `-[NSCoder encodeConditionalObject:forKey:]`. - * @details An encoding method for subclasses to override to conditionally encode an object, preserving common references to it, only if it has been unconditionally encoded. Subclasses must override this method if they support keyed coding. * @param object Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_conditional_object(const Object& object, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeDataObject:]`. - * @details Encodes a given data object. Subclasses must override this method. This method must be matched by a subsequent ''decodeDataObject'' message. * @param data Argument converted to the Objective-C parameter of the same role. */ void encode_data_object(const std::vector& data) const; /** * @brief Calls `-[NSCoder encodeDouble:forKey:]`. - * @details Encodes a double-precision floating point value and associates it with the string key. Subclasses must override this method if they perform keyed coding. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_double(double value, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeFloat:forKey:]`. - * @details Encodes a floating point value and associates it with the string key. Subclasses must override this method if they perform keyed coding. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_float(float value, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeInt32:forKey:]`. - * @details Encodes a 32-bit integer value and associates it with the string key. Subclasses must override this method if they perform keyed coding. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_int32(int value, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeInt64:forKey:]`. - * @details Encodes a 64-bit integer value and associates it with the string key. Subclasses must override this method if they perform keyed coding. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_int64(std::int64_t value, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeInt:forKey:]`. - * @details Encodes a C integer value and associates it with the string key. Subclasses must override this method if they perform keyed coding. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_int(int value, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeInteger:forKey:]`. - * @details Encodes an integer value and associates it with the string key. Subclasses must override this method if they perform keyed coding. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_integer(std::int64_t value, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeObject:]`. - * @details Encodes an object. 'NSCoder''s implementation simply invokes ''encodeValueOfObjCType:at:'' to encode 'object'. Subclasses can override this method to encode a reference to 'object' instead of 'object' itself. This method must be matched by a subsequent ''decodeObject'' message. * @param object Argument converted to the Objective-C parameter of the same role. */ void encode_object(const Object& object) const; /** * @brief Calls `-[NSCoder encodeObject:forKey:]`. - * @details Encodes an object and associates it with the string key. Subclasses must override this method to identify multiple encodings of 'object' and encode a reference to 'object' instead. * @param object Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ @@ -420,7 +382,6 @@ namespace cocoon void encode_point(const Point& point, const std::string& key) const; /** * @brief Calls `-[NSCoder encodePropertyList:]`. - * @details Encodes a property list. 'NSCoder''s implementation invokes ''encodeValueOfObjCType:at:'' to encode the property list. This method must be matched by a subsequent ''decodePropertyList'' message. * @param a_property_list Argument converted to the Objective-C parameter of the same role. */ void encode_property_list(const Object& a_property_list) const; @@ -437,7 +398,6 @@ namespace cocoon void encode_rect(const Rect& rect, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeRootObject:]`. - * @details An encoding method for subclasses to override to encode an interconnected group of objects, starting with the provided root object. 'NSCoder''s implementation simply invokes ''encodeObject:''. This method must be matched by a subsequent ''decodeObject'' message. * @param root_object Argument converted to the Objective-C parameter of the same role. */ void encode_root_object(const Object& root_object) const; @@ -454,20 +414,18 @@ namespace cocoon void encode_size(const Size& size, const std::string& key) const; /** * @brief Calls `-[NSCoder encodeValueOfObjCType:at:]`. - * @details Encodes a value of the given type at the given address. Subclasses must override this method, and match it with a subsequent ''decodeValueOfObjCType:at:size:'' message. When calling this method, 'type' must contain exactly one type code. You should not use this method to encode Objective-C objects. * @param type Argument converted to the Objective-C parameter of the same role. * @param addr Argument converted to the Objective-C parameter of the same role. */ void encode_value_of_obj_c_type(const std::string& type, const void* addr) const; /** * @brief Calls `-[NSCoder failWithError:]`. - * @details Signals to this coder that the decode operation has failed. Typically, you call this method in your ''NSCoding/init(coder:)'' implementation. You should set the error when you detect problems such as lack of secure coding, data corruption, or a domain validation failure. This method is only meaningful to call for decodes. The effect of calling this method depends on the value of ''decodingFailurePolicy'', as follows: - If the policy is ''DecodingFailurePolicy/raiseException'', calling this method throws an exception immediately. Swift code cannot catch this kind of exception. - If the policy is ''DecodingFailurePolicy/setErrorAndReturn'', calling this method sets the error property once per call to one of the 'decode' methods. Calling it repeatedly has no effect until the call stack unwinds to one of these methods' entry points. After calling 'failWithError:' within your ''NSCoding/init(coder:)'' implementation, you should clean up and return 'nil' as early as possible. - Parameter error: An error that indicates why decoding failed. + * @details \@abstract Signals to this coder that the decode has failed. \@parameter non-nil error that describes the reason why the decode failed \@discussion Sets an error on this NSCoder once per TopLevel decode; calling it repeatedly will have no effect until the call stack unwinds to one of the TopLevel decode entry-points. This method is only meaningful to call for decodes. Typically, you would want to call this method in your -initWithCoder: implementation when you detect situations like: - lack of secure coding - corruption of your data - domain validation failures After calling -failWithError: within your -initWithCoder: implementation, you should clean up and return nil as early as possible. Once an error has been signaled to a decoder, it remains set until it has handed off to the first TopLevel decode invocation above it. For example, consider the following call graph: A -decodeTopLevelObjectForKey:error: B -initWithCoder: C -decodeObjectForKey: D -initWithCoder: E -decodeObjectForKey: F -failWithError: In this case the error provided in stack-frame F will be returned via the outError in stack-frame A. Furthermore the result object from decodeTopLevelObjectForKey:error: will be nil, regardless of the result of stack-frame B. NSCoder implementations support two mechanisms for the stack-unwinding from F to A: - forced (NSException based) - particpatory (error based) The kind of unwinding you get is determined by the decodingFailurePolicy property of this NSCoder (which defaults to NSDecodingFailurePolicyRaiseException to match historical behavior). * @param error Argument converted to the Objective-C parameter of the same role. */ void fail_with_error(const Error& error) const; /** * @brief Calls `-[NSCoder versionForClassName:]`. - * @details This method is present for historical reasons and is not used with keyed archivers. - Returns: The version in effect for the class named 'className' or 'NSNotFound' if no class named 'className' exists. * @param class_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -479,19 +437,18 @@ namespace cocoon std::vector allowed_classes() const; /** * @brief Returns the `allowsKeyedCoding` property of `NSCoder`. - * @details A Boolean value that indicates whether the receiver supports keyed coding of objects. 'NO' by default. Concrete subclasses that support keyed coding, such as 'NSKeyedArchiver', need to override this property to return 'YES'. * @return The converted Objective-C result. */ bool allows_keyed_coding() const; /** * @brief Returns the `decodingFailurePolicy` property of `NSCoder`. - * @details The action the coder should take when decoding fails. A decode call can fail for the following reasons: - The keyed archive data is corrupt or missing. - A type mismatch occurs, such as expecting a class but encountering a numeric type instead. This also occurs when 'decodeInteger(forKey:)' encounters a value encoded as floating-point, or vice versa. - A secure coding violation occurs. This happens when you attempt to decode an object that doesn't conform to 'NSSecureCoding', or when the encoded type doesn't match any of the expected types. + * @details \@abstract Defines the behavior this NSCoder should take on decode failure (i.e. corrupt archive, invalid data, etc.). \@discussion The default result of this property is NSDecodingFailurePolicyRaiseException, subclasses can change this to an alternative policy. * @return The converted Objective-C result. */ DecodingFailurePolicy decoding_failure_policy() const; /** * @brief Returns the `error` property of `NSCoder`. - * @details An error in the top-level decode. The meaning of this property depends on the setting of the 'decodingFailurePolicy' property. For 'NSDecodingFailurePolicyRaiseException', this property is always 'nil'. For 'NSDecodingFailurePolicySetErrorAndReturn', a non-'nil' value represents the first error encountered while decoding the archive. While 'error' is non-'nil', all attempts to decode data from this coder will return a 'nil'/zero-equivalent value. This error is consumed by a top-level decode API, which resets the coder back to being able to potentially decode data. + * @details \@abstract The current error (if there is one) for the current TopLevel decode. \@discussion The meaning of this property changes based on the result of the decodingFailurePolicy property: For NSDecodingFailurePolicyRaiseException, this property will always be nil. For NSDecodingFailurePolicySetErrorAndReturn, this property can be non-nil, and if so, indicates that there was a failure while decoding the archive (specifically its the very first error encountered). While .error is non-nil, all attempts to decode data from this coder will return a nil/zero-equivalent value. This error is consumed by a TopLevel decode API (which resets this coder back to a being able to potentially decode data). * @return The converted Objective-C result. */ Error error() const; @@ -502,7 +459,6 @@ namespace cocoon bool requires_secure_coding() const; /** * @brief Returns the `systemVersion` property of `NSCoder`. - * @details The system version in effect for the archive. During encoding, the current version. During decoding, the version that was in effect when the data was encoded. Subclasses that implement decoding must override this property to return the system version of the data being decoded. * @return The converted Objective-C result. */ unsigned int system_version() const; diff --git a/include/generated/collection_view_layout.h b/include/generated/collection_view_layout.h index 3ba49596..ae303802 100644 --- a/include/generated/collection_view_layout.h +++ b/include/generated/collection_view_layout.h @@ -144,7 +144,7 @@ namespace cocoon CollectionViewLayoutAttributes layout_attributes_for_drop_target_at_point(const Point& point_in_collection_view) const; /** * @brief Calls `-[NSCollectionViewLayout layoutAttributesForElementsInRect:]`. - * @details NSCollectionView calls these four methods to determine the layout information. Implement -layoutAttributesForElementsInRect: to return layout attributes for for supplementary or decoration views, or to perform layout in an as-needed-on-screen fashion. Additionally, all layout subclasses should implement -layoutAttributesForItemAtIndexPath: to return layout attributes instances on demand for specific index paths. If the layout supports any supplementary or decoration view types, it should also implement the respective atIndexPath: methods for those types. During a batch update (-[NSCollectionView performBatchUpdates:completionHandler:], or a diffable data source's -applySnapshot:animatingDifferences:completion:), -layoutAttributesForItemAtIndexPath: must return non-nil attributes for every item that still exists after the update. Returning nil for such an item is a programming error and will raise an assertion. This normally means the layout's backing data (for example a section provider) or the data source's contents were changed out of step with the update; apply those changes as part of the update rather than before it. + * @details NSCollectionView calls these four methods to determine the layout information. Implement -layoutAttributesForElementsInRect: to return layout attributes for for supplementary or decoration views, or to perform layout in an as-needed-on-screen fashion. Additionally, all layout subclasses should implement -layoutAttributesForItemAtIndexPath: to return layout attributes instances on demand for specific index paths. If the layout supports any supplementary or decoration view types, it should also implement the respective atIndexPath: methods for those types. * @param rect Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ diff --git a/include/generated/comparison_predicate.h b/include/generated/comparison_predicate.h index c42ba324..90c81f39 100644 --- a/include/generated/comparison_predicate.h +++ b/include/generated/comparison_predicate.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSComparisonPredicate` (Foundation). - * @details A specialized predicate for comparing expressions. Use comparison predicates to compare the results of two expressions. You create a comparison predicate with an operator, a left expression, and a right expression, and use instances of the ''NSExpression'' class to represent those expressions. When you evaluate the predicate, it returns a 'BOOL' value as the result of invoking the operator with the results of evaluating the expressions. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Predicate. * @@ -47,7 +46,6 @@ namespace cocoon explicit ComparisonPredicate(Adopt adopt); /** * @brief Calls `+[NSComparisonPredicate predicateWithLeftExpression:rightExpression:customSelector:]`. - * @details Returns a new predicate formed by combining the left and right expressions using a given selector. - Parameters: - lhs: The left hand side expression. - rhs: The right hand side expression. - selector: The selector to use for comparison. The method defined by the selector must take a single argument and return a 'BOOL' value. - Returns: A new predicate formed by combining the left and right expressions using 'selector'. * @param lhs Argument converted to the Objective-C parameter of the same role. * @param rhs Argument converted to the Objective-C parameter of the same role. * @param selector Argument converted to the Objective-C parameter of the same role. @@ -56,7 +54,6 @@ namespace cocoon static ComparisonPredicate predicate_with_left_expression(const Expression& lhs, const Expression& rhs, const std::string& selector); /** * @brief Calls `+[NSComparisonPredicate predicateWithLeftExpression:rightExpression:modifier:type:options:]`. - * @details Creates and returns a predicate of a given type formed by combining given left and right expressions using a given modifier and options. - Parameters: - lhs: The left hand expression. - rhs: The right hand expression. - modifier: The modifier to apply. - type: The predicate operator type. - options: The options to apply. For no options, pass '0'. - Returns: A new predicate of type 'type' formed by combining the given left and right expressions using the 'modifier' and 'options'. * @param lhs Argument converted to the Objective-C parameter of the same role. * @param rhs Argument converted to the Objective-C parameter of the same role. * @param modifier Argument converted to the Objective-C parameter of the same role. @@ -67,37 +64,31 @@ namespace cocoon static ComparisonPredicate predicate_with_left_expression(const Expression& lhs, const Expression& rhs, ComparisonPredicateModifier modifier, PredicateOperatorType type, ComparisonPredicateOptions options); /** * @brief Returns the `comparisonPredicateModifier` property of `NSComparisonPredicate`. - * @details The comparison predicate modifier for the receiver. The default value is 'NSDirectPredicateModifier'. * @return The converted Objective-C result. */ ComparisonPredicateModifier comparison_predicate_modifier() const; /** * @brief Returns the `customSelector` property of `NSComparisonPredicate`. - * @details The selector for the receiver, or 'NULL' if there is none. * @return The converted Objective-C result. */ std::string custom_selector() const; /** * @brief Returns the `leftExpression` property of `NSComparisonPredicate`. - * @details The left expression for the receiver. * @return The converted Objective-C result. */ Expression left_expression() const; /** * @brief Returns the `options` property of `NSComparisonPredicate`. - * @details The options to use for the receiver. * @return The converted Objective-C result. */ ComparisonPredicateOptions options() const; /** * @brief Returns the `predicateOperatorType` property of `NSComparisonPredicate`. - * @details The predicate type for the receiver. * @return The converted Objective-C result. */ PredicateOperatorType predicate_operator_type() const; /** * @brief Returns the `rightExpression` property of `NSComparisonPredicate`. - * @details The right expression for the receiver. * @return The converted Objective-C result. */ Expression right_expression() const; diff --git a/include/generated/compound_predicate.h b/include/generated/compound_predicate.h index 8c4b6b71..2f423983 100644 --- a/include/generated/compound_predicate.h +++ b/include/generated/compound_predicate.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCompoundPredicate` (Foundation). - * @details A specialized predicate that evaluates logical combinations of other predicates. Use ''NSCompoundPredicate'' to create an 'AND' or 'OR' compound predicate of one or more other predicates, or the 'NOT' of a single predicate. For the logical 'AND' and 'OR' operations: - An 'AND' predicate with no subpredicates evaluates to \. - An 'OR' predicate with no subpredicates evaluates to \. - A compound predicate with one or more subpredicates evaluates to the truth of its subpredicates. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Predicate. * @@ -44,34 +43,30 @@ namespace cocoon explicit CompoundPredicate(Adopt adopt); /** * @brief Calls `+[NSCompoundPredicate andPredicateWithSubpredicates:]`. - * @details Returns a new predicate that you form using an AND operation on the predicates in a specified array. - Parameters: - subpredicates: An array of 'NSPredicate' objects. - Returns: A new predicate formed by AND-ing the predicates specified by 'subpredicates'. An AND predicate with no subpredicates evaluates to TRUE. + * @details Convenience Methods * @param subpredicates Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static CompoundPredicate and_predicate_with_subpredicates(const std::vector& subpredicates); /** * @brief Calls `+[NSCompoundPredicate notPredicateWithSubpredicate:]`. - * @details Returns a new predicate that you form using a NOT operation on a specified predicate. * @param predicate Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static CompoundPredicate not_predicate_with_subpredicate(const Predicate& predicate); /** * @brief Calls `+[NSCompoundPredicate orPredicateWithSubpredicates:]`. - * @details Returns a new predicate that you form using an OR operation on the predicates in a specified array. An OR predicate with no subpredicates evaluates to FALSE. * @param subpredicates Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static CompoundPredicate or_predicate_with_subpredicates(const std::vector& subpredicates); /** * @brief Returns the `compoundPredicateType` property of `NSCompoundPredicate`. - * @details The predicate type for the receiver. * @return The converted Objective-C result. */ CompoundPredicateType compound_predicate_type() const; /** * @brief Returns the `subpredicates` property of `NSCompoundPredicate`. - * @details The receiver's subpredicates. * @return The converted Objective-C result. */ std::vector subpredicates() const; diff --git a/include/generated/condition.h b/include/generated/condition.h index 60bc5878..e14104f4 100644 --- a/include/generated/condition.h +++ b/include/generated/condition.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCondition` (Foundation). - * @details A condition variable whose semantics follow those used for POSIX-style conditions. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -46,35 +45,29 @@ namespace cocoon explicit Condition(Adopt adopt); /** * @brief Calls `-[NSCondition broadcast]`. - * @details Signals the condition, waking up all waiting threads. */ void broadcast() const; /** * @brief Calls `-[NSCondition signal]`. - * @details Signals the condition, waking up one waiting thread. */ void signal_() const; /** * @brief Calls `-[NSCondition wait]`. - * @details Blocks the current thread until the condition is signaled. */ void wait() const; /** * @brief Calls `-[NSCondition waitUntilDate:]`. - * @details Blocks the current thread until the condition is signaled or the specified time limit is reached. * @param limit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool wait_until_date(const Date& limit) const; /** * @brief Returns the `name` property of `NSCondition`. - * @details The name associated with the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSCondition`. - * @details The name associated with the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; diff --git a/include/generated/condition_lock.h b/include/generated/condition_lock.h index e3cd9bac..5b2ceba7 100644 --- a/include/generated/condition_lock.h +++ b/include/generated/condition_lock.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSConditionLock` (Foundation). - * @details A lock that can be associated with specific, user-defined conditions. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,20 +47,17 @@ namespace cocoon explicit ConditionLock(Adopt adopt); /** * @brief Calls `-[NSConditionLock lockBeforeDate:]`. - * @details Attempts to acquire a lock before a given date and returns a Boolean value indicating whether the attempt was successful. * @param limit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool lock_before_date(const Date& limit) const; /** * @brief Calls `-[NSConditionLock lockWhenCondition:]`. - * @details Attempts to acquire a lock when the receiver's condition is equal to a specific value. * @param condition Argument converted to the Objective-C parameter of the same role. */ void lock_when_condition(std::int64_t condition) const; /** * @brief Calls `-[NSConditionLock lockWhenCondition:beforeDate:]`. - * @details Attempts to acquire a lock when the receiver's condition is equal to a specific value, and returns before a given date. * @param condition Argument converted to the Objective-C parameter of the same role. * @param limit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -69,38 +65,32 @@ namespace cocoon bool lock_when_condition(std::int64_t condition, const Date& limit) const; /** * @brief Calls `-[NSConditionLock tryLock]`. - * @details Attempts to acquire a lock and immediately returns a Boolean value that indicates whether the attempt was successful. * @return The converted Objective-C result. */ bool try_lock() const; /** * @brief Calls `-[NSConditionLock tryLockWhenCondition:]`. - * @details Attempts to acquire a lock if the receiver's condition is equal to a specific value and immediately returns a Boolean value that indicates whether the attempt was successful. * @param condition Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool try_lock_when_condition(std::int64_t condition) const; /** * @brief Calls `-[NSConditionLock unlockWithCondition:]`. - * @details Relinquishes the lock and sets the receiver's condition. * @param condition Argument converted to the Objective-C parameter of the same role. */ void unlock_with_condition(std::int64_t condition) const; /** * @brief Returns the `condition` property of `NSConditionLock`. - * @details The condition associated with the receiver. * @return The converted Objective-C result. */ std::int64_t condition() const; /** * @brief Returns the `name` property of `NSConditionLock`. - * @details The name associated with the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSConditionLock`. - * @details The name associated with the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; diff --git a/include/generated/connection.h b/include/generated/connection.h index 12b9de31..1e6ea50d 100644 --- a/include/generated/connection.h +++ b/include/generated/connection.h @@ -16,7 +16,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSConnection` (Foundation). - * @details \@DeprecationSummary { Use ''NSXPCConnection'' instead. } An object that manages the communication between objects in different threads or between a thread and a process running on a local or remote system. Connection objects form the backbone of the distributed objects mechanism and normally operate in the background. You use the methods of ''NSConnection'' explicitly when vending an object to other applications, when accessing such a vended object through a proxy, and when altering default communication parameters. At other times, you simply interact with a vended object or its proxy. A single connection object may be shared by multiple threads and used to access a vended object. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -60,54 +59,45 @@ namespace cocoon explicit Connection(Adopt adopt); /** * @brief Calls `-[NSConnection addRequestMode:]`. - * @details Adds 'rmode' to the set of run-loop input modes that the receiver uses for connection requests. The default input mode is 'NSDefaultRunLoopMode'. See the 'NSRunLoop' class specification for more information on input modes. * @param rmode Argument converted to the Objective-C parameter of the same role. */ void add_request_mode(const std::string& rmode) const; /** * @brief Calls `-[NSConnection addRunLoop:]`. - * @details Adds the specified run loop to the list of run loops on which the receiver listens for incoming messages. * @param runloop Argument converted to the Objective-C parameter of the same role. */ void add_run_loop(const RunLoop& runloop) const; /** * @brief Calls `+[NSConnection allConnections]`. - * @details Returns an array of all existing 'NSConnection' objects. * @return The converted Objective-C result. */ static std::vector all_connections(); /** * @brief Calls `+[NSConnection currentConversation]`. - * @details Returns an object representing an ongoing conversation triggered by a received message. * @return The converted Objective-C result. */ static Object current_conversation(); /** * @brief Calls `-[NSConnection dispatchWithComponents:]`. - * @details Dispatches Distributed Objects component data received over the wire. NSPort subclasses should use this method to ask a connection object to dispatch Distributed Objects component data. This will decode the data, authenticate, and send the message. * @param components Argument converted to the Objective-C parameter of the same role. */ void dispatch_with_components(const std::vector& components) const; /** * @brief Calls `-[NSConnection enableMultipleThreads]`. - * @details Configures the receiver to allow requests from multiple threads to the remote object, without requiring each thread to maintain its own connection. */ void enable_multiple_threads() const; /** * @brief Calls `-[NSConnection invalidate]`. - * @details Invalidates the receiver. */ void invalidate() const; /** * @brief Calls `-[NSConnection registerName:]`. - * @details Registers the receiver with the default 'NSPortNameServer' under the given name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool register_name(const std::string& name) const; /** * @brief Calls `-[NSConnection registerName:withNameServer:]`. - * @details Registers the receiver with the given name server under the given name. * @param name Argument converted to the Objective-C parameter of the same role. * @param server Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -115,24 +105,20 @@ namespace cocoon bool register_name(const std::string& name, const PortNameServer& server) const; /** * @brief Calls `-[NSConnection removeRequestMode:]`. - * @details Removes 'rmode' from the set of run-loop input modes the receiver uses for connection requests. * @param rmode Argument converted to the Objective-C parameter of the same role. */ void remove_request_mode(const std::string& rmode) const; /** * @brief Calls `-[NSConnection removeRunLoop:]`. - * @details Removes the specified run loop from the list of run loops on which the receiver listens for incoming messages. * @param runloop Argument converted to the Objective-C parameter of the same role. */ void remove_run_loop(const RunLoop& runloop) const; /** * @brief Calls `-[NSConnection runInNewThread]`. - * @details Configures the receiver to use a new thread for its connection. */ void run_in_new_thread() const; /** * @brief Calls `+[NSConnection serviceConnectionWithName:rootObject:]`. - * @details Returns an 'NSConnection' object that both listens for contact from external clients and has a designated root object, using the default name server. * @param name Argument converted to the Objective-C parameter of the same role. * @param root Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -140,7 +126,6 @@ namespace cocoon static Connection service_connection_with_name(const std::string& name, const Object& root); /** * @brief Calls `+[NSConnection serviceConnectionWithName:rootObject:usingNameServer:]`. - * @details Returns an 'NSConnection' object that both listens for contact from external clients and has a designated root object. * @param name Argument converted to the Objective-C parameter of the same role. * @param root Argument converted to the Objective-C parameter of the same role. * @param server Argument converted to the Objective-C parameter of the same role. @@ -149,97 +134,81 @@ namespace cocoon static Connection service_connection_with_name(const std::string& name, const Object& root, const PortNameServer& server); /** * @brief Returns the `independentConversationQueueing` property of `NSConnection`. - * @details A Boolean value that indicates whether the receiver handles requests atomically. * @return The converted Objective-C result. */ bool independent_conversation_queueing() const; /** * @brief Sets the `independentConversationQueueing` property of `NSConnection`. - * @details A Boolean value that indicates whether the receiver handles requests atomically. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_independent_conversation_queueing(bool value) const; /** * @brief Returns the `localObjects` property of `NSConnection`. - * @details All local objects that are being vended over the connection. * @return The converted Objective-C result. */ std::vector local_objects() const; /** * @brief Returns the `multipleThreadsEnabled` property of `NSConnection`. - * @details A Boolean value that indicates whether the receiver supports requests from multiple threads. * @return The converted Objective-C result. */ bool multiple_threads_enabled() const; /** * @brief Returns the `receivePort` property of `NSConnection`. - * @details The port on which the receiver receives messages. * @return The converted Objective-C result. */ Port receive_port() const; /** * @brief Returns the `remoteObjects` property of `NSConnection`. - * @details The proxies for all remote objects that have been received over the connection but have not yet been deallocated. * @return The converted Objective-C result. */ std::vector remote_objects() const; /** * @brief Returns the `replyTimeout` property of `NSConnection`. - * @details The timeout interval for replies. * @return The converted Objective-C result. */ double reply_timeout() const; /** * @brief Sets the `replyTimeout` property of `NSConnection`. - * @details The timeout interval for replies. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_reply_timeout(double value) const; /** * @brief Returns the `requestModes` property of `NSConnection`. - * @details The set of request modes the receiver's receive port is registered for with its 'NSRunLoop' object. * @return The converted Objective-C result. */ std::vector request_modes() const; /** * @brief Returns the `requestTimeout` property of `NSConnection`. - * @details The timeout interval for outgoing requests. * @return The converted Objective-C result. */ double request_timeout() const; /** * @brief Sets the `requestTimeout` property of `NSConnection`. - * @details The timeout interval for outgoing requests. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_request_timeout(double value) const; /** * @brief Returns the `rootObject` property of `NSConnection`. - * @details The object that the receiver makes available to other applications or threads. * @return The converted Objective-C result. */ Object root_object() const; /** * @brief Sets the `rootObject` property of `NSConnection`. - * @details The object that the receiver makes available to other applications or threads. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_root_object(const Object& value) const; /** * @brief Returns the `sendPort` property of `NSConnection`. - * @details The port on which the receiver sends messages. * @return The converted Objective-C result. */ Port send_port() const; /** * @brief Returns the `statistics` property of `NSConnection`. - * @details A dictionary containing various statistics for the receiver. An 'NSDictionary' object containing various statistics for the receiver, such as the number of vended objects, the number of requests and replies, and so on. The statistics dictionary should be used only for debugging purposes. * @return The converted Objective-C result. */ std::map statistics() const; /** * @brief Returns the `valid` property of `NSConnection`. - * @details A Boolean value that indicates whether the receiver is known to be valid. * @return The converted Objective-C result. */ bool is_valid() const; diff --git a/include/generated/constants.h b/include/generated/constants.h index 6a3f2a19..74379241 100644 --- a/include/generated/constants.h +++ b/include/generated/constants.h @@ -2037,8 +2037,6 @@ namespace cocoon static std::string source_text_scaling_document_attribute(); /// @brief Value of the SDK constant `NSCocoaVersionDocumentAttribute`. static std::string cocoa_version_document_attribute(); - /// @brief Value of the SDK constant `NSPaperMarginDocumentAttribute`. - static std::string paper_margin_document_attribute(); /// @brief Value of the SDK constant `NSConvertedDocumentAttribute`. static std::string converted_document_attribute(); /// @brief Value of the SDK constant `NSFileTypeDocumentAttribute`. @@ -3618,10 +3616,6 @@ namespace cocoon static std::string text_checking_selected_range_key(); /// @brief Value of the SDK constant `NSTextCheckingGenerateInlinePredictionsKey`. static std::string text_checking_generate_inline_predictions_key(); - /// @brief Value of the SDK constant `NSTextCheckingAutomaticCapitalizationEnabledKey`. - static std::string text_checking_automatic_capitalization_enabled_key(); - /// @brief Value of the SDK constant `NSTextCheckingWaitForAllGrammarCheckingResultsKey`. - static std::string text_checking_wait_for_all_grammar_checking_results_key(); }; /** @brief Named constants of type `NSTextContentType`; each function reads the SDK symbol at runtime. */ diff --git a/include/generated/control.h b/include/generated/control.h index c1072881..202b2050 100644 --- a/include/generated/control.h +++ b/include/generated/control.h @@ -62,17 +62,6 @@ namespace cocoon * @return The converted Objective-C result. */ bool abort_editing() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSControl addTarget:action:forControlEvents:]`. - * @details Associates a target object and action method with one or more control events. You can call this method multiple times to specify multiple target-action pairs for a particular event. Passing 'nil' as the target routes the action message up the responder chain. The control does not retain the target. - * @param target Argument converted to the Objective-C parameter of the same role. - * @param action Argument converted to the Objective-C parameter of the same role. - * @param control_events Argument converted to the Objective-C parameter of the same role. - */ - void add_target(const Object& target, const std::string& action, ControlEvents control_events) const; -#endif - /** * @brief Calls `-[NSControl currentEditor]`. * @return The converted Objective-C result. @@ -125,17 +114,6 @@ namespace cocoon * @param sender Argument converted to the Objective-C parameter of the same role. */ void perform_click(const Object& sender) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSControl removeTarget:action:forControlEvents:]`. - * @details Stops the delivery of the specified events to the given target object. Pass 'nil' as the action to remove all actions for the target. - * @param target Argument converted to the Objective-C parameter of the same role. - * @param action Argument converted to the Objective-C parameter of the same role. - * @param control_events Argument converted to the Objective-C parameter of the same role. - */ - void remove_target(const Object& target, const std::string& action, ControlEvents control_events) const; -#endif - /** * @brief Calls `-[NSControl selectCell:]`. * @param cell Argument converted to the Objective-C parameter of the same role. diff --git a/include/generated/counted_set_base.h b/include/generated/counted_set_base.h index 234ea347..ba9c393e 100644 --- a/include/generated/counted_set_base.h +++ b/include/generated/counted_set_base.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCountedSet` (Foundation). - * @details A mutable, unordered collection of distinct objects that may appear more than once in the collection. Each distinct object inserted into an 'NSCountedSet' object has a counter associated with it. 'NSCountedSet' keeps track of the number of times objects are inserted and requires that objects be removed the same number of times. Thus, there is only one instance of an object in an 'NSSet' object even if the object has been added to the set multiple times. The 'count' method defined by the superclass 'NSSet' has special significance; it returns the number of distinct objects, not the total number of times objects are represented in the set. The 'NSSet' and 'NSMutableSet' classes are provided for static and dynamic sets, respectively, whose elements are distinct. While 'NSCountedSet' and 'CFBag' are not toll-free bridged, they provide similar functionality. For more information about 'CFBag', see the 'CFBag'. \#\#\# Subclassing Notes Because 'NSCountedSet' is not a class cluster, it does not have primitive methods that provide the basis for its implementation. In general, there should be little need for subclassing. \#\#\#\# Methods to Override If you subclass 'NSCountedSet', you must override any method of which you want to change the behavior. If you change the primitive behavior of an 'NSCountedSet', for instance if you change how objects are stored, you must override all of the affected methods. These include: - 'addObject:' - 'removeObject:' - 'objectEnumerator' - 'countForObject:' If you change the primitive behavior, you must also override the primitive methods of 'NSSet' and 'NSMutableSet'. + * @details Counted Set * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref CountedSet to supply ObjectType. * @@ -46,26 +46,22 @@ namespace cocoon explicit CountedSetBase(Adopt adopt); /** * @brief Calls `-[NSCountedSet addObject:]`. - * @details Adds a given object to the set. If 'object' is already a member, 'addObject:' increments the count associated with the object. If 'object' is not already a member, it is sent a 'retain' message. - Parameter object: The object to add to the set. * @param object Argument converted to the Objective-C parameter of the same role. */ void add_object(const Object& object) const; /** * @brief Calls `-[NSCountedSet countForObject:]`. - * @details Returns the count associated with a given object in the set. - Parameter object: The object for which to return the count. - Returns: The count associated with 'object' in the set, which can be thought of as the number of occurrences of 'object' present in the set. * @param object Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t count_for_object(const Object& object) const; /** * @brief Calls `-[NSCountedSet objectEnumerator]`. - * @details Returns an enumerator object that lets you access each object in the set once, independent of its count. If you add a given object to the counted set multiple times, an enumeration of the set will produce that object only once. You shouldn't modify the set during enumeration. If you intend to modify the set, use the 'allObjects' method to create a "snapshot," then enumerate the snapshot and modify the original set. - Returns: An enumerator object that lets you access each object in the set once, independent of its count. * @return The converted Objective-C result. */ EnumeratorBase object_enumerator() const; /** * @brief Calls `-[NSCountedSet removeObject:]`. - * @details Removes a given object from the set. If 'object' is present in the set, decrements the count associated with it. If the count is decremented to '0', 'object' is removed from the set. 'removeObject:' does nothing if 'object' is not present in the set. - Parameter object: The object to remove from the set. * @param object Argument converted to the Objective-C parameter of the same role. */ void remove_object(const Object& object) const; diff --git a/include/generated/create_command.h b/include/generated/create_command.h index 0738dee7..7309fe8f 100644 --- a/include/generated/create_command.h +++ b/include/generated/create_command.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSCreateCommand` (Foundation). - * @details A command that creates a scriptable object. An instance of 'NSCreateCommand' creates the specified scriptable object (such as a document), optionally supplying the new object with the specified attributes. This command corresponds to AppleScript's 'make' command. 'NSCreateCommand' is part of Cocoa's built-in scripting support. Most applications don't need to subclass 'NSCreateCommand' or invoke its methods. When an instance of 'NSCreateCommand' is executed, it creates a new object using '[[theClassToBeCreated allocWithZone:NULL] init]' (where 'theClassToBeCreated' is the class of the object to be created), unless the command has a 'with data' argument. In the latter case, the new object is created by invoking '[[NSScriptCoercionHandler sharedCoercionHandler] coerceValue:theDataAsAnObject toClass:theClassToBeCreated]'. Any properties specified by a 'with properties' argument are then set in the new object using '-setScriptingProperties:'. If an 'NSCreateCommand' object with no argument corresponding to the 'at' parameter is executed (for example, 'tell application "Mail" to make new mailbox with properties {name:"testFolder"}'), and the receiver of the command (not necessarily the application object) has a to-many relationship to objects of the class to be instantiated, and the class description for the receiving class returns \ when sent an 'isLocationRequiredToCreateForKey:' message, the 'NSCreateCommand' object creates a new object and sends the receiver an \ message to place the new object in the container. This is part of Cocoa's scripting support for inserting newly-created objects into containers without explicitly specifying a location. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptCommand. * @@ -35,13 +34,11 @@ namespace cocoon explicit CreateCommand(Adopt adopt); /** * @brief Returns the `createClassDescription` property of `NSCreateCommand`. - * @details The class description for the class that is to be created. * @return The converted Objective-C result. */ ScriptClassDescription create_class_description() const; /** * @brief Returns the `resolvedKeyDictionary` property of `NSCreateCommand`. - * @details The key dictionary with Apple event codes resolved to actual key names. * @return The converted Objective-C result. */ std::map resolved_key_dictionary() const; diff --git a/include/generated/data_detector.h b/include/generated/data_detector.h index 9880551b..3ae91a6c 100644 --- a/include/generated/data_detector.h +++ b/include/generated/data_detector.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSDataDetector` (Foundation). - * @details A specialized regular expression object that matches natural language text for predefined data patterns. Find dates, addresses, links, phone numbers, and transit information in natural language text with 'NSDataDetector'. 'NSDataDetector' returns the results of matching content in ''NSTextCheckingResult'' objects. The ''NSTextCheckingResult'' objects that 'NSDataDetector' returns are different from those that ''NSRegularExpression'' returns. The results are one of the data detector's types and contain the corresponding properties. For example, results of type ''NSTextCheckingResult/CheckingType/date'' have a ''NSTextCheckingResult/date'', ''NSTextCheckingResult/timeZone'', and ''NSTextCheckingResult/duration''; and results of type ''NSTextCheckingResult/CheckingType/link'' have a ''NSTextCheckingResult/url''. > Important: > Don't use 'NSDataDetector' to validate data. 'NSDataDetector' discards potential matches in case of uncertainty. Use a class specific to the type of data for validation instead. For example, attempt to instantiate a ''URL'' object using ''URL/init(string:)'' to validate a URL string. A valid URL string returns an instance of ''URL'', while an invalid URL string returns \. \#\#\# Examples The following shows several graduated examples of using the 'NSDataDetector' class. This code fragment creates a data detector that finds URL links and phone numbers. If an error occurs, it returns in 'error'. '''objc NSError error = nil; NSDataDetector detector = [NSDataDetector dataDetectorWithTypes:NSTextCheckingTypeLink|NSTextCheckingTypePhoneNumber error:&error]; ''' After creating the data detector instance, you can determine the number of matches within a range of a string using the 'NSRegularExpression' method ''NSRegularExpression/numberOfMatches(in:options:range:)''. '''objc NSUInteger numberOfMatches = [detector numberOfMatchesInString:string options:0 range:NSMakeRange(0, [string length])]; ''' If you're interested only in the overall range of the first match, the ''NSRegularExpression/numberOfMatches(in:options:range:)'' method provides it. However, with data detectors, this is less likely than with regular expressions because clients are usually interested in additional information as well. The additional information available depends on the type of the result. For results of type ''NSTextCheckingResult/CheckingType/link'', it's the 'URL' property that's significant. For results of type 'NSTextCheckingTypePhoneNumber' , it's the 'phoneNumber' property instead. The ''NSRegularExpression/matches(in:options:range:)'' method is similar to ''NSRegularExpression/firstMatch(in:options:range:)'', except that it returns all matches rather than only the first. The following code fragment finds all the matches for links and phone numbers in a string: '''objc NSArray matches = [detector matchesInString:string options:0 range:NSMakeRange(0, [string length])]; for (NSTextCheckingResult match in matches) { NSRange matchRange = [match range]; if ([match resultType] == NSTextCheckingTypeLink) { NSURL url = [match URL]; } else if ([match resultType] == NSTextCheckingTypePhoneNumber) { NSString phoneNumber = [match phoneNumber]; } } ''' The 'NSRegularExpression' block object enumerator is the most general and flexible of the matching methods. It allows you to iterate through matches in a string, performing arbitrary actions on each as specified by the code in the block, and to stop partway through if desired. In the following code fragment, the iteration stops after finding a certain number of matches: '''objc block NSUInteger count = 0; [detector enumerateMatchesInString:string options:0 range:NSMakeRange(0, [string length]) usingBlock:^(NSTextCheckingResult match, NSMatchingFlags flags, BOOL stop){ NSRange matchRange = [match range]; if ([match resultType] == NSTextCheckingTypeLink) { NSURL url = [match URL]; } else if ([match resultType] == NSTextCheckingTypePhoneNumber) { NSString phoneNumber = [match phoneNumber]; } if (++count >= 100) stop = YES; }]; ''' > Note: > Only use 'NSDataDetector' on natural language text. > > If you expect text to be in a particular format, use an ''Formatter'' or ''ValueTransformer'' subclass instead. For instance, if you're expecting a date field to be an ISO 8601 timestamp, use ''DateFormatter'' to parse that into an ''NSDate'' object. > > If the text is in a machine-readable format, such as XML or JSON, extract the natural language text, such as by using ''XMLParser'' or ''JSONSerialization'', and match on that rather than attempt to match on the entire document. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref RegularExpression. * @@ -35,7 +34,6 @@ namespace cocoon explicit DataDetector(Adopt adopt); /** * @brief Returns the `checkingTypes` property of `NSDataDetector`. - * @details The checking types for the data detector. The supported subset of checking types are specified in ''NSTextCheckingResult/CheckingType''. Those constants can be combined using the C-bitwise OR operator. Currently, the supported data detector checking types are: ''NSTextCheckingResult/CheckingType/date'', ''NSTextCheckingResult/CheckingType/address'', ''NSTextCheckingResult/CheckingType/link'', phone number, and transit information. * @return The converted Objective-C result. */ std::uint64_t checking_types() const; diff --git a/include/generated/date.h b/include/generated/date.h index 4d840c0d..b9e350da 100644 --- a/include/generated/date.h +++ b/include/generated/date.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSDate` (Foundation). - * @details A representation of a specific point in time, independent of any calendar or time zone. In Swift, use this type when you need reference semantics or other Foundation-specific behavior. ''NSDate'' objects encapsulate a single point in time, independent of any particular calendrical system or time zone. Date objects are immutable, representing an invariant time interval relative to an absolute reference date (00:00:00 UTC on 1 January 2001). The ''NSDate'' class provides methods for comparing dates, calculating the time interval between two dates, and creating a new date from a time interval relative to another date. ''NSDate'' objects can be used in conjunction with ''DateFormatter'' objects to create localized representations of dates and times, as well as with ''NSCalendar'' objects to perform calendar arithmetic. ''NSDate'' is toll-free bridged with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. > Important: > The Swift overlay to the Foundation framework provides the ''Date'' structure, which bridges to the ''NSDate'' class. For more information about value types, see \. \#\#\# Subclassing Notes You might subclass ''NSDate'' in order to make it easier to work with a particular calendrical system, or to work with date and time values with a finer temporal granularity. \#\#\#\# Methods to Override and Other Requirements If you want to subclass ''NSDate'' to obtain behavior different than that provided by the private or public subclasses, you must: - Declare a suitable instance variable to hold the date and time value (relative to an absolute reference date) - Override the ''timeIntervalSinceReferenceDate-property'' instance method to provide the correct date and time value based on your instance variable - Override ''init(timeIntervalSinceReferenceDate:)'', one of the designated initializer methods - If creating a subclass that represents a calendrical system, define methods that partition past and future periods into the units of this calendar - Implement the methods required by the ''NSCopying'' and [NSCoding](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/BuildingCocoaApps/WritingSwiftClassesWithObjective-CBehavior.html\#//apple_ref/doc/uid/TP40014216-CH5-ID152) protocols, because ''NSDate'' adopts these protocols \#\#\#\# Special Considerations Your subclass may use a different reference date than the absolute reference date used by ''NSDate'' (00:00:00 UTC on 1 January 2001). If it does, it must still use the absolute reference date in its implementations of the methods ''timeIntervalSinceReferenceDate-property'' and ''init(timeIntervalSinceReferenceDate:)''. That is, the reference date referred to in the titles of these methods is the absolute reference date. If you do not use the absolute reference date in these methods, comparisons between ''NSDate'' objects of your subclass and 'NSDate' objects of a private subclass will not work. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,92 +44,78 @@ namespace cocoon explicit Date(Adopt adopt); /** * @brief Calls `-[NSDate compare:]`. - * @details Indicates the temporal ordering of the receiver and another given date. - Parameter other: The date with which to compare the receiver. This value must not be 'nil'. If the value is 'nil', the behavior is undefined and may change in future versions of macOS. - Returns: 'NSOrderedSame' if the two dates are exactly equal, 'NSOrderedDescending' if the receiver is later in time than 'other', and 'NSOrderedAscending' if the receiver is earlier in time than 'other'. This method detects sub-second differences between dates. If you want to compare dates with a less fine granularity, use 'timeIntervalSinceDate:' to compare the two dates. * @param other Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ComparisonResult compare(const Date& other) const; /** * @brief Calls `-[NSDate dateByAddingTimeInterval:]`. - * @details Returns a new date object that is set to a given number of seconds relative to the receiver. - Parameter ti: The number of seconds to add to the receiver. Use a negative value for seconds to have the returned object specify a date before the receiver. - Returns: A new 'NSDate' object that is set to 'seconds' seconds relative to the receiver. The date returned might have a representation different from the receiver's. * @param ti Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Date date_by_adding_time_interval(double ti) const; /** * @brief Calls `-[NSDate descriptionWithLocale:]`. - * @details Returns a string representation of the date using the given locale. - Parameter locale: An 'NSLocale' object. If you pass 'nil', 'NSDate' formats the date in the same way as the 'description' property. - Returns: A string representation of the receiver, using the given locale, or if the locale argument is 'nil', in the international format 'YYYY-MM-DD HH:MM:SS +/-HHMM', where '+/-HHMM' represents the time zone offset in hours and minutes from UTC (for example, "2001-03-24 10:45:32 +0600"). * @param locale Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string description_with_locale(const Object& locale) const; /** * @brief Calls `-[NSDate earlierDate:]`. - * @details Returns the earlier of the receiver and another given date. - Parameter anotherDate: The date with which to compare the receiver. - Returns: The earlier of the receiver and 'anotherDate', determined using 'timeIntervalSinceDate:'. If the receiver and 'anotherDate' represent the same date, returns the receiver. * @param another_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Date earlier_date(const Date& another_date) const; /** * @brief Calls `-[NSDate isEqualToDate:]`. - * @details Returns a Boolean value that indicates whether a given object is a date that is exactly equal the receiver. - Parameter otherDate: The date to compare with the receiver. - Returns: 'YES' if the 'otherDate' is an 'NSDate' object and is exactly equal to the receiver, otherwise 'NO'. This method detects sub-second differences between dates. If you want to compare dates with a less fine granularity, use 'timeIntervalSinceDate:' to compare the two dates. * @param other_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equal_to_date(const Date& other_date) const; /** * @brief Calls `-[NSDate laterDate:]`. - * @details Returns the later of the receiver and another given date. - Parameter anotherDate: The date with which to compare the receiver. - Returns: The later of the receiver and 'anotherDate', determined using 'timeIntervalSinceDate:'. If the receiver and 'anotherDate' represent the same date, returns the receiver. * @param another_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Date later_date(const Date& another_date) const; /** * @brief Calls `-[NSDate timeIntervalSinceDate:]`. - * @details Returns the interval between the receiver and another given date. - Parameter anotherDate: The date with which to compare the receiver. You must pass a non-'nil' date object. - Returns: The interval between the receiver and the 'anotherDate' parameter. If the receiver is earlier than 'anotherDate', the return value is negative. If 'anotherDate' is 'nil', the results are undefined. * @param another_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double time_interval_since_date(const Date& another_date) const; /** * @brief Returns the `description` property of `NSDate`. - * @details A string representation of the date object. The representation is useful for debugging only. There are a number of options to acquire a formatted string for a date including: date formatters (see 'NSDateFormatter'), and the 'NSDate' methods 'descriptionWithLocale:'. * @return The converted Objective-C result. */ std::string description() const; /** * @brief Returns the `distantFuture` property of `NSDate`. - * @details A date object representing a date in the distant future. You can pass this value when an 'NSDate' object is required to have the date argument essentially ignored. For example, the 'NSWindow' method 'nextEventMatchingMask:untilDate:inMode:dequeue:' returns 'nil' if an event specified in the event mask does not happen before the specified date. You can use the object returned by 'distantFuture' as the date argument to wait indefinitely for the event to occur. * @return The converted Objective-C result. */ static Date distant_future(); /** * @brief Returns the `distantPast` property of `NSDate`. - * @details A date object representing a date in the distant past. You can use this object as a control date, a guaranteed temporal boundary. * @return The converted Objective-C result. */ static Date distant_past(); /** * @brief Returns the `now` property of `NSDate`. - * @details The current date and time, as of the time of access. This is equivalent to initializing a new instance with 'NSDate()' (or '[[NSDate alloc] init]' in Objective-C). The 'NSDate' instance doesn't automatically update its time after you retrieve it. * @return The converted Objective-C result. */ static Date now(); /** * @brief Returns the `timeIntervalSince1970` property of `NSDate`. - * @details The interval between the date object and 00:00:00 UTC on 1 January 1970. This property's value is negative if the date object is earlier than 00:00:00 UTC on 1 January 1970. * @return The converted Objective-C result. */ double time_interval_since1970() const; /** * @brief Returns the `timeIntervalSinceNow` property of `NSDate`. - * @details The interval between the date object and the current date and time. If the date object is earlier than the current date and time, this property's value is negative. * @return The converted Objective-C result. */ double time_interval_since_now() const; /** * @brief Returns the `timeIntervalSinceReferenceDate` property of `NSDate`. - * @details The interval between the date object and 00:00:00 UTC on 1 January 2001. This property's value is negative if the date object is earlier than the system's absolute reference date (00:00:00 UTC on 1 January 2001). * @return The converted Objective-C result. */ double time_interval_since_reference_date() const; diff --git a/include/generated/date_components.h b/include/generated/date_components.h index 3ee315fd..261675b8 100644 --- a/include/generated/date_components.h +++ b/include/generated/date_components.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDateComponents` (Foundation). - * @details An object that specifies a date or time in terms of units (such as year, month, day, hour, and minute) to be evaluated in a calendar system and time zone. In Swift, this object bridges to ''DateComponents''; use ''NSDateComponents'' when you need reference semantics or other Foundation-specific behavior. ''NSDateComponents'' encapsulates the components of a date in an extendable, object-oriented manner. It's used to specify a date by providing the temporal components that make up a date and time: hour, minutes, seconds, day, month, year, and so on. You can also use it to specify a duration of time, for example, 5 hours and 16 minutes. An ''NSDateComponents'' object is not required to define all the component fields. When a new instance of ''NSDateComponents'' is created, the date components are set to ''NSDateComponentUndefined''. > Important: > An ''NSDateComponents'' object is meaningless in itself; you need to know what calendar it is interpreted against, and you need to know whether the values are absolute values of the units, or quantities of the units. An instance of ''NSDateComponents'' is not responsible for answering questions about a date beyond the information with which it was initialized. For example, if you initialize one with May 4, 2017, its weekday is ''NSDateComponentUndefined'', not Thursday. To get the correct day of the week, you must create a suitable instance of ''NSCalendar'', create an ''NSDate'' object using ''NSCalendar/date(from:)'' and then use ''NSCalendar/components(:from:)'' to retrieve the weekday—as illustrated in the following example. \@TabNavigator { \@Tab("Swift") { '''swift let dateComponents = NSDateComponents() dateComponents.day = 4 dateComponents.month = 5 dateComponents.year = 2017 if let gregorianCalendar = NSCalendar(calendarIdentifier: .gregorian), let date = gregorianCalendar.date(from: dateComponents as DateComponents) { let weekday = gregorianCalendar.component(.weekday, from: date) print(weekday) // 5, which corresponds to Thursday in the Gregorian Calendar } ''' } \@Tab("Objective-C") { '''objc NSDateComponents dateComponents = [[NSDateComponents alloc] init]; dateComponents.day = 4; dateComponents.month = 5; dateComponents.year = 2017; NSCalendar gregorianCalendar = [[NSCalendar alloc] initWithCalendarIdentifier:NSCalendarIdentifierGregorian]; NSDate date = [gregorianCalendar dateFromComponents:dateComponents]; NSInteger weekday = [gregorianCalendar component:NSCalendarUnitWeekday fromDate:date]; NSLog(\@"\%d", weekday); // 5, which corresponds to Thursday in the Gregorian Calendar ''' } } For more details, see [Calendars, Date Components, and Calendar Units](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DatesAndTimes/Articles/dtCalendars.html\#//apple_ref/doc/uid/TP40003470) in [Date and Time Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DatesAndTimes/DatesAndTimes.html\#//apple_ref/doc/uid/10000039i). > Important: > The Swift overlay to the Foundation framework provides the ''DateComponents'' structure, which bridges to the ''NSDateComponents'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -73,127 +72,106 @@ namespace cocoon std::int64_t value_for_component(CalendarUnit unit) const; /** * @brief Returns the `calendar` property of `NSDateComponents`. - * @details The calendar used to interpret the date components. * @return The converted Objective-C result. */ Calendar calendar() const; /** * @brief Sets the `calendar` property of `NSDateComponents`. - * @details The calendar used to interpret the date components. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_calendar(const Calendar& value) const; /** * @brief Returns the `date` property of `NSDateComponents`. - * @details The date calculated from the current components using the stored calendar. * @return The converted Objective-C result. */ Date date() const; /** * @brief Returns the `day` property of `NSDateComponents`. - * @details The number of days. * @return The converted Objective-C result. */ std::int64_t day() const; /** * @brief Sets the `day` property of `NSDateComponents`. - * @details The number of days. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_day(std::int64_t value) const; /** * @brief Returns the `dayOfYear` property of `NSDateComponents`. - * @details The day of the year value of the date components. * @return The converted Objective-C result. */ std::int64_t day_of_year() const; /** * @brief Sets the `dayOfYear` property of `NSDateComponents`. - * @details The day of the year value of the date components. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_day_of_year(std::int64_t value) const; /** * @brief Returns the `era` property of `NSDateComponents`. - * @details The number of eras. * @return The converted Objective-C result. */ std::int64_t era() const; /** * @brief Sets the `era` property of `NSDateComponents`. - * @details The number of eras. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_era(std::int64_t value) const; /** * @brief Returns the `hour` property of `NSDateComponents`. - * @details The number of hour units for the receiver. * @return The converted Objective-C result. */ std::int64_t hour() const; /** * @brief Sets the `hour` property of `NSDateComponents`. - * @details The number of hour units for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_hour(std::int64_t value) const; /** * @brief Returns the `leapMonth` property of `NSDateComponents`. - * @details A Boolean value that indicates whether the month is a leap month. * @return The converted Objective-C result. */ bool is_leap_month() const; /** * @brief Sets the `leapMonth` property of `NSDateComponents`. - * @details A Boolean value that indicates whether the month is a leap month. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_leap_month(bool value) const; /** * @brief Returns the `minute` property of `NSDateComponents`. - * @details The number of minute units for the receiver. * @return The converted Objective-C result. */ std::int64_t minute() const; /** * @brief Sets the `minute` property of `NSDateComponents`. - * @details The number of minute units for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minute(std::int64_t value) const; /** * @brief Returns the `month` property of `NSDateComponents`. - * @details The number of months. * @return The converted Objective-C result. */ std::int64_t month() const; /** * @brief Sets the `month` property of `NSDateComponents`. - * @details The number of months. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_month(std::int64_t value) const; /** * @brief Returns the `nanosecond` property of `NSDateComponents`. - * @details The number of nanosecond units for the receiver. * @return The converted Objective-C result. */ std::int64_t nanosecond() const; /** * @brief Sets the `nanosecond` property of `NSDateComponents`. - * @details The number of nanosecond units for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_nanosecond(std::int64_t value) const; /** * @brief Returns the `quarter` property of `NSDateComponents`. - * @details The number of quarters. * @return The converted Objective-C result. */ std::int64_t quarter() const; /** * @brief Sets the `quarter` property of `NSDateComponents`. - * @details The number of quarters. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_quarter(std::int64_t value) const; @@ -209,25 +187,21 @@ namespace cocoon void set_repeated_day(bool value) const; /** * @brief Returns the `second` property of `NSDateComponents`. - * @details The number of second units for the receiver. * @return The converted Objective-C result. */ std::int64_t second() const; /** * @brief Sets the `second` property of `NSDateComponents`. - * @details The number of second units for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_second(std::int64_t value) const; /** * @brief Returns the `timeZone` property of `NSDateComponents`. - * @details The time zone used to interpret the date components. * @return The converted Objective-C result. */ TimeZone time_zone() const; /** * @brief Sets the `timeZone` property of `NSDateComponents`. - * @details The time zone used to interpret the date components. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_time_zone(const TimeZone& value) const; @@ -239,73 +213,61 @@ namespace cocoon bool is_valid_date() const; /** * @brief Returns the `weekOfMonth` property of `NSDateComponents`. - * @details The week number of the months. * @return The converted Objective-C result. */ std::int64_t week_of_month() const; /** * @brief Sets the `weekOfMonth` property of `NSDateComponents`. - * @details The week number of the months. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_week_of_month(std::int64_t value) const; /** * @brief Returns the `weekOfYear` property of `NSDateComponents`. - * @details The ISO 8601 week date of the year. * @return The converted Objective-C result. */ std::int64_t week_of_year() const; /** * @brief Sets the `weekOfYear` property of `NSDateComponents`. - * @details The ISO 8601 week date of the year. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_week_of_year(std::int64_t value) const; /** * @brief Returns the `weekday` property of `NSDateComponents`. - * @details The number of the weekdays. * @return The converted Objective-C result. */ std::int64_t weekday() const; /** * @brief Sets the `weekday` property of `NSDateComponents`. - * @details The number of the weekdays. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_weekday(std::int64_t value) const; /** * @brief Returns the `weekdayOrdinal` property of `NSDateComponents`. - * @details The ordinal number of weekdays. * @return The converted Objective-C result. */ std::int64_t weekday_ordinal() const; /** * @brief Sets the `weekdayOrdinal` property of `NSDateComponents`. - * @details The ordinal number of weekdays. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_weekday_ordinal(std::int64_t value) const; /** * @brief Returns the `year` property of `NSDateComponents`. - * @details The number of years. * @return The converted Objective-C result. */ std::int64_t year() const; /** * @brief Sets the `year` property of `NSDateComponents`. - * @details The number of years. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_year(std::int64_t value) const; /** * @brief Returns the `yearForWeekOfYear` property of `NSDateComponents`. - * @details The ISO 8601 week-numbering year. * @return The converted Objective-C result. */ std::int64_t year_for_week_of_year() const; /** * @brief Sets the `yearForWeekOfYear` property of `NSDateComponents`. - * @details The ISO 8601 week-numbering year. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_year_for_week_of_year(std::int64_t value) const; diff --git a/include/generated/date_components_formatter.h b/include/generated/date_components_formatter.h index 2399e7b2..0c47923d 100644 --- a/include/generated/date_components_formatter.h +++ b/include/generated/date_components_formatter.h @@ -14,7 +14,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDateComponentsFormatter` (Foundation). - * @details A formatter that creates string representations of quantities of time. An ''DateComponentsFormatter'' object takes quantities of time and formats them as a user-readable string. Use a date components formatter to create strings for your app's interface. The formatter object has many options for creating both abbreviated and expanded strings. The formatter takes the current user's locale and language into account when generating strings. To use this class, create an instance, configure its properties, and call one of its methods to generate an appropriate string. The properties of this class let you configure the calendar and specify the date and time units you want displayed in the resulting string. The listing below shows how to configure a formatter to create the string "About 5 minutes remaining". \@TabNavigator { \@Tab("Swift") { '''swift let formatter = DateComponentsFormatter() formatter.unitsStyle = .full formatter.includesApproximationPhrase = true formatter.includesTimeRemainingPhrase = true formatter.allowedUnits = [.minute] // Use the configured formatter to generate the string. let outputString = formatter.string(from: 300.0) ''' } \@Tab("Objective-C") { '''objc NSDateComponentsFormatter formatter = [[NSDateComponentsFormatter alloc] init]; formatter.unitsStyle = NSDateComponentsFormatterUnitsStyleFull; formatter.includesApproximationPhrase = YES; formatter.includesTimeRemainingPhrase = YES; formatter.allowedUnits = NSCalendarUnitMinute; // Use the configured formatter to generate the string. NSString outputString = [formatter stringFromTimeInterval:300.0]; ''' } } The methods of this class may be called safely from any thread of your app. It is also safe to share a single instance of this class from multiple threads, with the caveat that you should not change the configuration of the object while another thread is using it to generate a string. > Tip: > In Swift, you can use ''Date/RelativeFormatStyle'' rather than ''DateComponentsFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. + * @details NSDateComponentsFormatter provides locale-correct and flexible string formatting of quantities of time, such as "1 day" or "1h 10m", as specified by NSDateComponents. For formatting intervals of time (such as "2PM to 5PM"), see NSDateIntervalFormatter. NSDateComponentsFormatter is thread-safe, in that calling methods on it from multiple threads will not cause crashes or incorrect results, but it makes no attempt to prevent confusion when one thread sets something and another thread isn't expecting it to change. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -54,7 +54,6 @@ namespace cocoon using Formatter::string_for_object_value; /** * @brief Calls `+[NSDateComponentsFormatter localizedStringFromDateComponents:unitsStyle:]`. - * @details Returns a localized string based on the specified date components and style option. Use this convenience method to format a string using the default formatter values, with the exception of the 'unitsStyle' value. \@param components The value to format. \@param unitsStyle The style for the resulting units. Use this parameter to specify whether you want the resulting string to use an abbreviated or more spelled out format. \@return A string containing the localized date and time information. * @param components Argument converted to the Objective-C parameter of the same role. * @param units_style Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -62,14 +61,14 @@ namespace cocoon static std::string localized_string_from_date_components(const DateComponents& components, DateComponentsFormatterUnitsStyle units_style); /** * @brief Calls `-[NSDateComponentsFormatter stringForObjectValue:]`. - * @details Returns a formatted string based on the date information in the specified object. \@param obj An object containing the date and time information to format. The object in this parameter must be an instance of 'NSDateComponents'. \@return A formatted string representing the specified date information. + * @details 'obj' must be an instance of NSDateComponents. * @param obj Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_for_object_value(const Object& obj) const; /** * @brief Calls `-[NSDateComponentsFormatter stringFromDate:toDate:]`. - * @details Returns a formatted string based on the time difference between two dates. This method calculates the elapsed time between the 'startDate' and 'endDate' values and uses that information to generate the string. For example, if there is exactly one hour and ten minutes difference between the start and end dates, generating an abbreviated string would result in a string of "1h 10m". Note that this is still formatting the quantity of time between the dates, not the pair of dates itself. For strings like "Feb 22nd - Feb 28th", use 'NSDateIntervalFormatter'. \@param startDate The start time. This parameter must not be 'nil'. \@param endDate The end time. This parameter must not be 'nil'. \@return A formatted string representing the specified time information. + * @details Normally, NSDateComponentsFormatter will calculate as though counting from referenceDate (e.g. in February, 1 month formatted as a number of days will be 28). -stringFromDate:toDate: calculates from the passed-in startDate instead. See 'allowedUnits' for how the default set of allowed units differs from -stringFromDateComponents:. Note that this is still formatting the quantity of time between the dates, not the pair of dates itself. For strings like "Feb 22nd - Feb 28th", use NSDateIntervalFormatter. * @param start_date Argument converted to the Objective-C parameter of the same role. * @param end_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -77,63 +76,63 @@ namespace cocoon std::string string_from_date(const Date& start_date, const Date& end_date) const; /** * @brief Calls `-[NSDateComponentsFormatter stringFromDateComponents:]`. - * @details Returns a formatted string based on the specified date component information. Use this method to format date information that is already broken down into the component day and time values. \@param components A date components object containing the date and time information to format. The 'allowedUnits' property determines which date components are actually used to generate the string. All other date components are ignored. This parameter must not be 'nil'. \@return A formatted string representing the specified date information. + * @details Convenience method for formatting an NSDateComponents object. This calculates the count of the unit(s) starting from referenceDate. * @param components Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_date_components(const DateComponents& components) const; /** * @brief Calls `-[NSDateComponentsFormatter stringFromTimeInterval:]`. - * @details Returns a formatted string based on the specified number of seconds. This method formats the specified number of seconds into the appropriate units. For example, if the formatter allows the display of minutes and seconds, creating an abbreviated string for the value 70 seconds results in the string "1m 10s". \@param ti The time interval, measured in seconds. The value must be a finite number. Negative numbers are treated as positive numbers when creating the string. \@return A formatted string representing the specified time interval. + * @details Convenience method for formatting a number of seconds. See 'allowedUnits' for how the default set of allowed units differs from -stringFromDateComponents:. This calculates the count of the unit(s) from referenceDate to the passed-in time interval. * @param ti Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_time_interval(double ti) const; /** * @brief Returns the `allowedUnits` property of `NSDateComponentsFormatter`. - * @details The bitmask of calendrical units such as day and month to include in the output string. The allowed calendar units are: - 'NSCalendarUnitYear' - 'NSCalendarUnitMonth' - 'NSCalendarUnitWeekOfMonth' (used to mean "quantity of weeks") - 'NSCalendarUnitDay' - 'NSCalendarUnitHour' - 'NSCalendarUnitMinute' - 'NSCalendarUnitSecond' Assigning any other calendar units to this property results in an exception. + * @details Bitmask of units to include. Set to 0 to get the default behavior. Note that, especially if the maximum number of units is low, unit collapsing is on, or zero dropping is on, not all allowed units may actually be used for a given NSDateComponents. Default value is the components of the passed-in NSDateComponents object, or years | months | weeks | days | hours | minutes | seconds if passed an NSTimeInterval or pair of NSDates. Allowed units are: NSCalendarUnitYear NSCalendarUnitMonth NSCalendarUnitWeekOfMonth (used to mean "quantity of weeks") NSCalendarUnitDay NSCalendarUnitHour NSCalendarUnitMinute NSCalendarUnitSecond Specifying any other NSCalendarUnits will result in an exception. * @return The converted Objective-C result. */ CalendarUnit allowed_units() const; /** * @brief Sets the `allowedUnits` property of `NSDateComponentsFormatter`. - * @details The bitmask of calendrical units such as day and month to include in the output string. The allowed calendar units are: - 'NSCalendarUnitYear' - 'NSCalendarUnitMonth' - 'NSCalendarUnitWeekOfMonth' (used to mean "quantity of weeks") - 'NSCalendarUnitDay' - 'NSCalendarUnitHour' - 'NSCalendarUnitMinute' - 'NSCalendarUnitSecond' Assigning any other calendar units to this property results in an exception. + * @details Bitmask of units to include. Set to 0 to get the default behavior. Note that, especially if the maximum number of units is low, unit collapsing is on, or zero dropping is on, not all allowed units may actually be used for a given NSDateComponents. Default value is the components of the passed-in NSDateComponents object, or years | months | weeks | days | hours | minutes | seconds if passed an NSTimeInterval or pair of NSDates. Allowed units are: NSCalendarUnitYear NSCalendarUnitMonth NSCalendarUnitWeekOfMonth (used to mean "quantity of weeks") NSCalendarUnitDay NSCalendarUnitHour NSCalendarUnitMinute NSCalendarUnitSecond Specifying any other NSCalendarUnits will result in an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allowed_units(CalendarUnit value) const; /** * @brief Returns the `allowsFractionalUnits` property of `NSDateComponentsFormatter`. - * @details A Boolean indicating whether non-integer units may be used for values. Fractional units may be used when a value cannot be exactly represented using the available units. For example, if minutes are not allowed, the value "1h 30m" could be formatted as "1.5h". The default value of this property is 'NO'. + * @details Choose whether non-integer units should be used to handle display of values that can't be exactly represented with the allowed units. For example, if minutes aren't allowed, then "1h 30m" could be formatted as "1.5h". Default is NO. * @return The converted Objective-C result. */ bool allows_fractional_units() const; /** * @brief Sets the `allowsFractionalUnits` property of `NSDateComponentsFormatter`. - * @details A Boolean indicating whether non-integer units may be used for values. Fractional units may be used when a value cannot be exactly represented using the available units. For example, if minutes are not allowed, the value "1h 30m" could be formatted as "1.5h". The default value of this property is 'NO'. + * @details Choose whether non-integer units should be used to handle display of values that can't be exactly represented with the allowed units. For example, if minutes aren't allowed, then "1h 30m" could be formatted as "1.5h". Default is NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_fractional_units(bool value) const; /** * @brief Returns the `calendar` property of `NSDateComponentsFormatter`. - * @details The default calendar to use when formatting date components. The formatter uses the calendar in this property to format values that do not have an inherent calendar of their own. For example, the formatter uses this calendar when formatting an 'NSTimeInterval' value. The default value of this property is the autoupdating current calendar. Setting this property to 'nil' causes the formatter to use the Gregorian calendar with the 'en_US_POSIX' locale. + * @details Specifies the locale and calendar to use for formatting date components that do not themselves have calendars. Defaults to NSAutoupdatingCurrentCalendar. If set to nil, uses the gregorian calendar with the en_US_POSIX locale. * @return The converted Objective-C result. */ Calendar calendar() const; /** * @brief Sets the `calendar` property of `NSDateComponentsFormatter`. - * @details The default calendar to use when formatting date components. The formatter uses the calendar in this property to format values that do not have an inherent calendar of their own. For example, the formatter uses this calendar when formatting an 'NSTimeInterval' value. The default value of this property is the autoupdating current calendar. Setting this property to 'nil' causes the formatter to use the Gregorian calendar with the 'en_US_POSIX' locale. + * @details Specifies the locale and calendar to use for formatting date components that do not themselves have calendars. Defaults to NSAutoupdatingCurrentCalendar. If set to nil, uses the gregorian calendar with the en_US_POSIX locale. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_calendar(const Calendar& value) const; /** * @brief Returns the `collapsesLargestUnit` property of `NSDateComponentsFormatter`. - * @details A Boolean value indicating whether to collapse the largest unit into smaller units when a certain threshold is met. An example of when this property might apply is when expressing 63 seconds worth of time. When this property is set to 'YES', the formatted value would be "63s". When the value of this property is 'NO', the formatted value would be "1m 3s". The default value of this property is 'NO'. + * @details Choose whether to express largest units just above the threshold for the next lowest unit as a larger quantity of the lower unit. For example: "1m 3s" vs "63s". Default is NO. * @return The converted Objective-C result. */ bool collapses_largest_unit() const; /** * @brief Sets the `collapsesLargestUnit` property of `NSDateComponentsFormatter`. - * @details A Boolean value indicating whether to collapse the largest unit into smaller units when a certain threshold is met. An example of when this property might apply is when expressing 63 seconds worth of time. When this property is set to 'YES', the formatted value would be "63s". When the value of this property is 'NO', the formatted value would be "1m 3s". The default value of this property is 'NO'. + * @details Choose whether to express largest units just above the threshold for the next lowest unit as a larger quantity of the lower unit. For example: "1m 3s" vs "63s". Default is NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_collapses_largest_unit(bool value) const; @@ -151,73 +150,73 @@ namespace cocoon void set_formatting_context(FormattingContext value) const; /** * @brief Returns the `includesApproximationPhrase` property of `NSDateComponentsFormatter`. - * @details A Boolean value indicating whether the resulting phrase reflects an inexact time value. Setting the value of this property to 'YES' adds phrasing to output strings to reflect that the given time value is approximate and not exact. Using this property yields more correct phrasing than simply prepending the string "About" to an output string. The default value of this property is 'NO'. + * @details Choose whether to indicate that the allowed units/insignificant units choices lead to inexact results. In some languages, simply prepending "about " to the string will produce incorrect results; this handles those cases correctly. Default is NO. * @return The converted Objective-C result. */ bool includes_approximation_phrase() const; /** * @brief Sets the `includesApproximationPhrase` property of `NSDateComponentsFormatter`. - * @details A Boolean value indicating whether the resulting phrase reflects an inexact time value. Setting the value of this property to 'YES' adds phrasing to output strings to reflect that the given time value is approximate and not exact. Using this property yields more correct phrasing than simply prepending the string "About" to an output string. The default value of this property is 'NO'. + * @details Choose whether to indicate that the allowed units/insignificant units choices lead to inexact results. In some languages, simply prepending "about " to the string will produce incorrect results; this handles those cases correctly. Default is NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_approximation_phrase(bool value) const; /** * @brief Returns the `includesTimeRemainingPhrase` property of `NSDateComponentsFormatter`. - * @details A Boolean value indicating whether output strings reflect the amount of time remaining. Setting this property to 'YES' results in output strings like "30 minutes remaining". The default value of this property is 'NO'. + * @details Choose whether to produce strings like "35 minutes remaining". Default is NO. * @return The converted Objective-C result. */ bool includes_time_remaining_phrase() const; /** * @brief Sets the `includesTimeRemainingPhrase` property of `NSDateComponentsFormatter`. - * @details A Boolean value indicating whether output strings reflect the amount of time remaining. Setting this property to 'YES' results in output strings like "30 minutes remaining". The default value of this property is 'NO'. + * @details Choose whether to produce strings like "35 minutes remaining". Default is NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_time_remaining_phrase(bool value) const; /** * @brief Returns the `maximumUnitCount` property of `NSDateComponentsFormatter`. - * @details The maximum number of time units to include in the output string. Use this property to limit the number of units displayed in the resulting string. For example, with this property set to 2, instead of "1h 10m, 30s", the resulting string would be "1h 10m". Use this property when you are constrained for space or want to round up values to the nearest large unit. The default value of this property is '0', which does not cause the elimination of any units. + * @details Choose whether or not, and at which point, to round small units in large values to zero. Examples: 1h 10m 30s, maximumUnitCount set to 0: "1h 10m 30s" 1h 10m 30s, maximumUnitCount set to 2: "1h 10m" 10m 30s, maximumUnitCount set to 0: "10m 30s" 10m 30s, maximumUnitCount set to 2: "10m 30s" Default is 0, which is interpreted as unlimited. * @return The converted Objective-C result. */ std::int64_t maximum_unit_count() const; /** * @brief Sets the `maximumUnitCount` property of `NSDateComponentsFormatter`. - * @details The maximum number of time units to include in the output string. Use this property to limit the number of units displayed in the resulting string. For example, with this property set to 2, instead of "1h 10m, 30s", the resulting string would be "1h 10m". Use this property when you are constrained for space or want to round up values to the nearest large unit. The default value of this property is '0', which does not cause the elimination of any units. + * @details Choose whether or not, and at which point, to round small units in large values to zero. Examples: 1h 10m 30s, maximumUnitCount set to 0: "1h 10m 30s" 1h 10m 30s, maximumUnitCount set to 2: "1h 10m" 10m 30s, maximumUnitCount set to 0: "10m 30s" 10m 30s, maximumUnitCount set to 2: "10m 30s" Default is 0, which is interpreted as unlimited. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum_unit_count(std::int64_t value) const; /** * @brief Returns the `referenceDate` property of `NSDateComponentsFormatter`. - * @details Where units have variable length (number of days in a month, number of hours in a day, etc.), 'NSDateComponentsFormatter' will calculate as though counting from the date specified by the 'referenceDate' in the appropriate calendar. Defaults to '[NSDate dateWithTimeIntervalSinceReferenceDate:0]' at the time of the '-stringForObjectValue:' call if not set. Set to 'nil' to get the default behavior. + * @details Where units have variable length (number of days in a month, number of hours in a day, etc...), NSDateComponentsFormatter will calculate as though counting from the date specified by the referenceDate in the appropriate calendar. Defaults to [NSDate dateWithTimeIntervalSinceReferenceDate:0] at the time of the -stringForObjectValue: call if not set. Set to nil to get the default behavior. * @return The converted Objective-C result. */ Date reference_date() const; /** * @brief Sets the `referenceDate` property of `NSDateComponentsFormatter`. - * @details Where units have variable length (number of days in a month, number of hours in a day, etc.), 'NSDateComponentsFormatter' will calculate as though counting from the date specified by the 'referenceDate' in the appropriate calendar. Defaults to '[NSDate dateWithTimeIntervalSinceReferenceDate:0]' at the time of the '-stringForObjectValue:' call if not set. Set to 'nil' to get the default behavior. + * @details Where units have variable length (number of days in a month, number of hours in a day, etc...), NSDateComponentsFormatter will calculate as though counting from the date specified by the referenceDate in the appropriate calendar. Defaults to [NSDate dateWithTimeIntervalSinceReferenceDate:0] at the time of the -stringForObjectValue: call if not set. Set to nil to get the default behavior. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_reference_date(const Date& value) const; /** * @brief Returns the `unitsStyle` property of `NSDateComponentsFormatter`. - * @details The formatting style for unit names. Configures the strings to use (if any) for unit names such as days, hours, minutes, and seconds. Use this property to specify whether you want abbreviated or shortened versions of unit names---for example, "hrs" instead of "hours". The default value of this property is 'NSDateComponentsFormatterUnitsStylePositional'. + * @details Choose how to indicate units. For example, 1h 10m vs 1:10. Default is NSDateComponentsFormatterUnitsStylePositional. * @return The converted Objective-C result. */ DateComponentsFormatterUnitsStyle units_style() const; /** * @brief Sets the `unitsStyle` property of `NSDateComponentsFormatter`. - * @details The formatting style for unit names. Configures the strings to use (if any) for unit names such as days, hours, minutes, and seconds. Use this property to specify whether you want abbreviated or shortened versions of unit names---for example, "hrs" instead of "hours". The default value of this property is 'NSDateComponentsFormatterUnitsStylePositional'. + * @details Choose how to indicate units. For example, 1h 10m vs 1:10. Default is NSDateComponentsFormatterUnitsStylePositional. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_units_style(DateComponentsFormatterUnitsStyle value) const; /** * @brief Returns the `zeroFormattingBehavior` property of `NSDateComponentsFormatter`. - * @details The formatting style for units whose value is 0. When the value for a particular unit is 0, the zero formatting behavior determines whether that value is retained or omitted from any resulting strings. For example, when the formatting behavior is 'NSDateComponentsFormatterZeroFormattingBehaviorDropTrailing', the value of one hour, ten minutes, and zero seconds would omit the mention of seconds. The default value of this property is 'NSDateComponentsFormatterZeroFormattingBehaviorDefault'. + * @details Bitmask specifying how to handle zeros in units. This includes both padding and dropping zeros so that a consistent number digits are displayed, causing updating displays to remain more stable. Default is NSDateComponentsFormatterZeroFormattingBehaviorDefault. If the combination of zero formatting behavior and style would lead to ambiguous date formats (for example, 1:10 meaning 1 hour, 10 seconds), NSDateComponentsFormatter will throw an exception. * @return The converted Objective-C result. */ DateComponentsFormatterZeroFormattingBehavior zero_formatting_behavior() const; /** * @brief Sets the `zeroFormattingBehavior` property of `NSDateComponentsFormatter`. - * @details The formatting style for units whose value is 0. When the value for a particular unit is 0, the zero formatting behavior determines whether that value is retained or omitted from any resulting strings. For example, when the formatting behavior is 'NSDateComponentsFormatterZeroFormattingBehaviorDropTrailing', the value of one hour, ten minutes, and zero seconds would omit the mention of seconds. The default value of this property is 'NSDateComponentsFormatterZeroFormattingBehaviorDefault'. + * @details Bitmask specifying how to handle zeros in units. This includes both padding and dropping zeros so that a consistent number digits are displayed, causing updating displays to remain more stable. Default is NSDateComponentsFormatterZeroFormattingBehaviorDefault. If the combination of zero formatting behavior and style would lead to ambiguous date formats (for example, 1:10 meaning 1 hour, 10 seconds), NSDateComponentsFormatter will throw an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_zero_formatting_behavior(DateComponentsFormatterZeroFormattingBehavior value) const; diff --git a/include/generated/date_formatter.h b/include/generated/date_formatter.h index d3f4cd6e..8415e82a 100644 --- a/include/generated/date_formatter.h +++ b/include/generated/date_formatter.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDateFormatter` (Foundation). - * @details A formatter that converts between dates and their textual representations. Instances of ''DateFormatter'' create string representations of ''NSDate'' objects, and convert textual representations of dates and times into ''NSDate'' objects. For user-visible representations of dates and times, ''DateFormatter'' provides a variety of localized presets and configuration options. For fixed format representations of dates and times, you can specify a custom format string. When working with date representations in ISO 8601 format, use ''ISO8601DateFormatter'' instead. To represent an interval between two ''NSDate'' objects, use ''DateIntervalFormatter'' instead. To represent a quantity of time specified by an ''NSDateComponents'' object, use ''DateComponentsFormatter'' instead. > Tip: > In Swift, you can use ''Date/FormatStyle'' or ''Date/VerbatimFormatStyle'' rather than ''DateFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. \#\#\# Working With User-Visible Representations of Dates and Times When displaying a date to a user, you set the ''dateStyle'' and ''timeStyle'' properties of the date formatter according to your particular needs. For example, if you want to show the month, day, and year without showing the time, you would set the ''dateStyle'' property to ''Style/long'' and the ''timeStyle'' property to ''Style/none''. Conversely, if you want to show only the time, you would set the 'dateStyle' property to ''Style/none'' and the ''timeStyle'' property to ''Style/short''. Based on the values of the ''dateStyle'' and ''timeStyle'' properties, ''DateFormatter'' provides a representation of a specified date that is appropriate for a given locale. \@TabNavigator { \@Tab("Swift") { '''swift let dateFormatter = DateFormatter() dateFormatter.dateStyle = .medium dateFormatter.timeStyle = .none let date = Date(timeIntervalSinceReferenceDate: 118800) // US English Locale (en_US) dateFormatter.locale = Locale(identifier: "en_US") print(dateFormatter.string(from: date)) // Jan 2, 2001 // French Locale (fr_FR) dateFormatter.locale = Locale(identifier: "fr_FR") print(dateFormatter.string(from: date)) // 2 janv. 2001 // Japanese Locale (ja_JP) dateFormatter.locale = Locale(identifier: "ja_JP") print(dateFormatter.string(from: date)) // 2001/01/02 ''' } \@Tab("Objective-C") { '''objc NSDateFormatter dateFormatter = [[NSDateFormatter alloc] init]; dateFormatter.dateStyle = NSDateFormatterMediumStyle; dateFormatter.timeStyle = NSDateFormatterNoStyle; NSDate date = [NSDate dateWithTimeIntervalSinceReferenceDate:118800]; // US English Locale (en_US) dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:\@"en_US"]; NSLog(\@"\%\@", [dateFormatter stringFromDate:date]); // Jan 2, 2001 // French Locale (fr_FR) dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:\@"fr_FR"]; NSLog(\@"\%\@", [dateFormatter stringFromDate:date]); // 2 janv. 2001 // Japanese Locale (ja_JP) dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:\@"ja_JP"]; NSLog(\@"\%\@", [dateFormatter stringFromDate:date]); // 2001/01/02 ''' } } If you need to define a format that cannot be achieved using the predefined styles, you can use the ''setLocalizedDateFormatFromTemplate(:)'' to specify a localized date format from a template. \@TabNavigator { \@Tab("Swift") { '''swift let dateFormatter = DateFormatter() let date = Date(timeIntervalSinceReferenceDate: 410220000) // US English Locale (en_US) dateFormatter.locale = Locale(identifier: "en_US") dateFormatter.setLocalizedDateFormatFromTemplate("MMMMd") // set template after setting locale print(dateFormatter.string(from: date)) // December 31 // British English Locale (en_GB) dateFormatter.locale = Locale(identifier: "en_GB") dateFormatter.setLocalizedDateFormatFromTemplate("MMMMd") // // set template after setting locale print(dateFormatter.string(from: date)) // 31 December ''' } \@Tab("Objective-C") { '''objc NSDateFormatter dateFormatter = [[NSDateFormatter alloc] init]; NSDate date = [NSDate dateWithTimeIntervalSinceReferenceDate:410220000]; // US English Locale (en_US) dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:\@"en_US"]; [dateFormatter setLocalizedDateFormatFromTemplate:\@"MMMMd"]; // set template after setting locale NSLog(\@"\%\@", [dateFormatter stringFromDate:date]); // December 31 // British English Locale (en_GB) dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:\@"en_GB"]; [dateFormatter setLocalizedDateFormatFromTemplate:\@"MMMMd"]; // set template after setting locale NSLog(\@"\%\@", [dateFormatter stringFromDate:date]); // 31 December ''' } } \#\#\# Working With Fixed Format Date Representations > Important: > In macOS 10.12 and later or iOS 10 and later, use the ''ISO8601DateFormatter'' class when working with ISO 8601 date representations. When working with fixed format dates, such as RFC 3339, you set the ''dateFormat'' property to specify a format string. For most fixed formats, you should also set the ''locale'' property to a POSIX locale ('"en_US_POSIX"'), and set the ''timeZone'' property to UTC. \@TabNavigator { \@Tab("Swift") { '''swift let RFC3339DateFormatter = DateFormatter() RFC3339DateFormatter.locale = Locale(identifier: "en_US_POSIX") RFC3339DateFormatter.dateFormat = "yyyy-MM-dd'T'HH:mm:ssZZZZZ" RFC3339DateFormatter.timeZone = TimeZone(secondsFromGMT: 0) / 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from UTC (Pacific Standard Time) let string = "1996-12-19T16:39:57-08:00" let date = RFC3339DateFormatter.date(from: string) ''' } \@Tab("Objective-C") { '''objc RFC3339DateFormatter = [[NSDateFormatter alloc] init]; RFC3339DateFormatter.locale = [NSLocale localeWithLocaleIdentifier:\@"en_US_POSIX"]; RFC3339DateFormatter.dateFormat = \@"yyyy-MM-dd'T'HH:mm:ssZZZZZ"; RFC3339DateFormatter.timeZone = [NSTimeZone timeZoneForSecondsFromGMT:0]; / 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from UTC (Pacific Standard Time) NSString string = \@"1996-12-19T16:39:57-08:00"; NSDate date = [RFC3339DateFormatter dateFromString:string]; ''' } } For more information, see [Technical Q&A QA1480 “NSDateFormatter and Internet Dates”](https://developer.apple.com/library/mac/qa/qa1480/). \#\#\# Thread Safety On iOS 7 and later 'NSDateFormatter' is thread safe. In macOS 10.9 and later 'NSDateFormatter' is thread safe so long as you are using the modern behavior in a 64-bit app. On earlier versions of the operating system, or when using the legacy formatter behavior or running in 32-bit in macOS, 'NSDateFormatter' is not thread safe, and you therefore must not mutate a date formatter simultaneously from multiple threads. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -54,7 +53,6 @@ namespace cocoon explicit DateFormatter(Adopt adopt); /** * @brief Calls `+[NSDateFormatter dateFormatFromTemplate:options:locale:]`. - * @details Returns a localized date format string representing the given date format components arranged appropriately for the specified locale. - Parameters: - tmplate: A string containing date format patterns (such as "MM" or "h"). - opts: No options are currently defined — pass '0'. - locale: The locale for which the template is required. - Returns: A localized date format string representing the date format components given in 'tmplate', arranged appropriately for the locale specified by 'locale'. The returned string may not contain exactly those components given in 'tmplate', but may — for example — have locale-specific adjustments applied. Different locales have different conventions for the ordering of date components. You use this method to get an appropriate format string for a given set of components for a specified locale (typically you use the current locale). * @param tmplate Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. * @param locale Argument converted to the Objective-C parameter of the same role. @@ -63,14 +61,12 @@ namespace cocoon static std::string date_format_from_template(const std::string& tmplate, std::uint64_t opts, const Locale& locale); /** * @brief Calls `-[NSDateFormatter dateFromString:]`. - * @details Returns a date representation of a specified string that the system interprets using the receiver's current settings. - Parameter string: The string to parse. - Returns: A date representation of 'string'. If 'dateFromString:' can't parse the string, returns 'nil'. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Date date_from_string(const std::string& string) const; /** * @brief Calls `+[NSDateFormatter localizedStringFromDate:dateStyle:timeStyle:]`. - * @details Returns a string representation of a specified date, that the system formats for the current locale using the specified date and time styles. - Parameters: - date: A date. - dstyle: A format style for the date. For possible values, see 'NSDateFormatterStyle'. - tstyle: A format style for the time. For possible values, see 'NSDateFormatterStyle'. - Returns: A localized string representation of 'date' using the specified date and time styles. This method uses a date formatter configured with the current default settings. The returned string is the same as if you configured and used a date formatter as shown in the following example: NSDateFormatter formatter = [[NSDateFormatter alloc] init]; formatter.formatterBehavior = NSDateFormatterBehavior10_4; formatter.dateStyle = dateStyle; formatter.timeStyle = timeStyle; NSString result = [formatter stringForObjectValue:date]; * @param date Argument converted to the Objective-C parameter of the same role. * @param dstyle Argument converted to the Objective-C parameter of the same role. * @param tstyle Argument converted to the Objective-C parameter of the same role. @@ -79,434 +75,363 @@ namespace cocoon static std::string localized_string_from_date(const Date& date, DateFormatterStyle dstyle, DateFormatterStyle tstyle); /** * @brief Calls `-[NSDateFormatter setLocalizedDateFormatFromTemplate:]`. - * @details Sets the date format from a template using the specified locale for the receiver. - Parameter dateFormatTemplate: A string containing date format patterns (such as "MM" or "h"). Calling this method is equivalent to, but not necessarily implemented as, setting the 'dateFormat' property to the result of calling the 'dateFormatFromTemplate:options:locale:' method, passing no options and the 'locale' property value. > Important: You should call this method only after setting the 'locale' of the receiver. + * @details A convenient way to generate an appropriate localized date format, and set it, in a single operation. Equivalent to, though not necessarily implemented as: formatter.dateFormat = [NSDateFormatter dateFormatFromTemplate:dateFormatTemplate options:0 locale:formatter.locale]; Note that the template string is used only to specify which date format components should be included. Ordering and other text will not be preserved. The parameter is also not stored, or updated when the locale or other options change, just as with the ‘dateFormat’ property. * @param date_format_template Argument converted to the Objective-C parameter of the same role. */ void set_localized_date_format_from_template(const std::string& date_format_template) const; /** * @brief Calls `-[NSDateFormatter stringFromDate:]`. - * @details Returns a string representation of a specified date that the system formats using the receiver's current settings. - Parameter date: The date to format. - Returns: A string representation of 'date'. * @param date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_date(const Date& date) const; /** * @brief Returns the `AMSymbol` property of `NSDateFormatter`. - * @details The AM symbol for the receiver. * @return The converted Objective-C result. */ std::string am_symbol() const; /** * @brief Sets the `AMSymbol` property of `NSDateFormatter`. - * @details The AM symbol for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_am_symbol(const std::string& value) const; /** * @brief Returns the `PMSymbol` property of `NSDateFormatter`. - * @details The PM symbol for the receiver. * @return The converted Objective-C result. */ std::string pm_symbol() const; /** * @brief Sets the `PMSymbol` property of `NSDateFormatter`. - * @details The PM symbol for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_pm_symbol(const std::string& value) const; /** * @brief Returns the `calendar` property of `NSDateFormatter`. - * @details The calendar for the receiver. If unspecified, the logical calendar for the current user is used. * @return The converted Objective-C result. */ Calendar calendar() const; /** * @brief Sets the `calendar` property of `NSDateFormatter`. - * @details The calendar for the receiver. If unspecified, the logical calendar for the current user is used. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_calendar(const Calendar& value) const; /** * @brief Returns the `dateFormat` property of `NSDateFormatter`. - * @details The date format string used by the receiver. You should only set this property when working with fixed format representations. For user-visible representations, you should use the 'dateStyle' and 'timeStyle' properties, or the 'setLocalizedDateFormatFromTemplate:' method if your desired format cannot be achieved using the predefined styles; both of these properties and this method provide a localized date representation appropriate for display to the user. * @return The converted Objective-C result. */ std::string date_format() const; /** * @brief Sets the `dateFormat` property of `NSDateFormatter`. - * @details The date format string used by the receiver. You should only set this property when working with fixed format representations. For user-visible representations, you should use the 'dateStyle' and 'timeStyle' properties, or the 'setLocalizedDateFormatFromTemplate:' method if your desired format cannot be achieved using the predefined styles; both of these properties and this method provide a localized date representation appropriate for display to the user. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_date_format(const std::string& value) const; /** * @brief Returns the `dateStyle` property of `NSDateFormatter`. - * @details The date style of the receiver. * @return The converted Objective-C result. */ DateFormatterStyle date_style() const; /** * @brief Sets the `dateStyle` property of `NSDateFormatter`. - * @details The date style of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_date_style(DateFormatterStyle value) const; /** * @brief Returns the `defaultDate` property of `NSDateFormatter`. - * @details The default date for the receiver. By default, this property is 'nil'. * @return The converted Objective-C result. */ Date default_date() const; /** * @brief Sets the `defaultDate` property of `NSDateFormatter`. - * @details The default date for the receiver. By default, this property is 'nil'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_default_date(const Date& value) const; /** * @brief Returns the `defaultFormatterBehavior` property of `NSDateFormatter`. - * @details Returns the default formatting behavior for instances of the class. For iOS and for macOS applications linked against macOS 10.5 and later, the default is 'NSDateFormatterBehavior10_4'. * @return The converted Objective-C result. */ static DateFormatterBehavior default_formatter_behavior(); /** * @brief Sets the `defaultFormatterBehavior` property of `NSDateFormatter`. - * @details Returns the default formatting behavior for instances of the class. For iOS and for macOS applications linked against macOS 10.5 and later, the default is 'NSDateFormatterBehavior10_4'. * @param value Argument converted to the Objective-C parameter of the same role. */ static void set_default_formatter_behavior(DateFormatterBehavior value); /** * @brief Returns the `doesRelativeDateFormatting` property of `NSDateFormatter`. - * @details A Boolean value that indicates whether the receiver uses phrases such as "today" and "tomorrow" for the date component. 'YES' if the receiver uses relative date formatting, otherwise 'NO'. If a date formatter uses relative date formatting, where possible it replaces the date component of its output with a phrase — such as "today" or "tomorrow" — that indicates a relative date. The available phrases depend on the locale for the date formatter; whereas, for dates in the future, English may only allow "tomorrow," French may allow "the day after the day after tomorrow." * @return The converted Objective-C result. */ bool does_relative_date_formatting() const; /** * @brief Sets the `doesRelativeDateFormatting` property of `NSDateFormatter`. - * @details A Boolean value that indicates whether the receiver uses phrases such as "today" and "tomorrow" for the date component. 'YES' if the receiver uses relative date formatting, otherwise 'NO'. If a date formatter uses relative date formatting, where possible it replaces the date component of its output with a phrase — such as "today" or "tomorrow" — that indicates a relative date. The available phrases depend on the locale for the date formatter; whereas, for dates in the future, English may only allow "tomorrow," French may allow "the day after the day after tomorrow." * @param value Argument converted to the Objective-C parameter of the same role. */ void set_does_relative_date_formatting(bool value) const; /** * @brief Returns the `eraSymbols` property of `NSDateFormatter`. - * @details The era symbols for the receiver. An array containing 'NSString' objects representing the era symbols for the receiver (for example, {"B.C.E.", "C.E."}). * @return The converted Objective-C result. */ std::vector era_symbols() const; /** * @brief Sets the `eraSymbols` property of `NSDateFormatter`. - * @details The era symbols for the receiver. An array containing 'NSString' objects representing the era symbols for the receiver (for example, {"B.C.E.", "C.E."}). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_era_symbols(const std::vector& value) const; /** * @brief Returns the `formatterBehavior` property of `NSDateFormatter`. - * @details The formatter behavior for the receiver. * @return The converted Objective-C result. */ DateFormatterBehavior formatter_behavior() const; /** * @brief Sets the `formatterBehavior` property of `NSDateFormatter`. - * @details The formatter behavior for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_formatter_behavior(DateFormatterBehavior value) const; /** * @brief Returns the `formattingContext` property of `NSDateFormatter`. - * @details The capitalization formatting context used when formatting a date. The formatting context allows the formatter to apply appropriate capitalization depending on how the string will be used, and whether the locale makes capitalization distinctions. * @return The converted Objective-C result. */ FormattingContext formatting_context() const; /** * @brief Sets the `formattingContext` property of `NSDateFormatter`. - * @details The capitalization formatting context used when formatting a date. The formatting context allows the formatter to apply appropriate capitalization depending on how the string will be used, and whether the locale makes capitalization distinctions. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_formatting_context(FormattingContext value) const; /** * @brief Returns the `generatesCalendarDates` property of `NSDateFormatter`. - * @details Indicates whether the formatter generates the deprecated calendar date type. This property is 'YES' if the formatter generates the deprecated 'NSCalendarDate' type, and is 'NO' otherwise. You should use 'NSDate' and 'NSCalendar' rather than 'NSCalendarDate'. * @return The converted Objective-C result. */ bool generates_calendar_dates() const; /** * @brief Sets the `generatesCalendarDates` property of `NSDateFormatter`. - * @details Indicates whether the formatter generates the deprecated calendar date type. This property is 'YES' if the formatter generates the deprecated 'NSCalendarDate' type, and is 'NO' otherwise. You should use 'NSDate' and 'NSCalendar' rather than 'NSCalendarDate'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_generates_calendar_dates(bool value) const; /** * @brief Returns the `gregorianStartDate` property of `NSDateFormatter`. - * @details The start date of the Gregorian calendar for the receiver. This is used to specify the start date for the Gregorian calendar switch from the Julian calendar. Different locales switched at different times. Normally you should just accept the locale's default date for the switch. * @return The converted Objective-C result. */ Date gregorian_start_date() const; /** * @brief Sets the `gregorianStartDate` property of `NSDateFormatter`. - * @details The start date of the Gregorian calendar for the receiver. This is used to specify the start date for the Gregorian calendar switch from the Julian calendar. Different locales switched at different times. Normally you should just accept the locale's default date for the switch. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_gregorian_start_date(const Date& value) const; /** * @brief Returns the `lenient` property of `NSDateFormatter`. - * @details A Boolean value that indicates whether the receiver uses heuristics when parsing a string. 'YES' if the receiver has been set to use heuristics when parsing a string to guess at the date which is intended, otherwise 'NO'. If a formatter is set to be lenient, when parsing a string it uses heuristics to guess at the date which is intended. As with any guessing, it may get the result date wrong (that is, a date other than that which was intended). * @return The converted Objective-C result. */ bool is_lenient() const; /** * @brief Sets the `lenient` property of `NSDateFormatter`. - * @details A Boolean value that indicates whether the receiver uses heuristics when parsing a string. 'YES' if the receiver has been set to use heuristics when parsing a string to guess at the date which is intended, otherwise 'NO'. If a formatter is set to be lenient, when parsing a string it uses heuristics to guess at the date which is intended. As with any guessing, it may get the result date wrong (that is, a date other than that which was intended). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_lenient(bool value) const; /** * @brief Returns the `locale` property of `NSDateFormatter`. - * @details The locale for the receiver. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSDateFormatter`. - * @details The locale for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; /** * @brief Returns the `longEraSymbols` property of `NSDateFormatter`. - * @details The long era symbols for the receiver. An array containing 'NSString' objects representing the era symbols for the receiver (for example, {"Before Common Era", "Common Era"}). * @return The converted Objective-C result. */ std::vector long_era_symbols() const; /** * @brief Sets the `longEraSymbols` property of `NSDateFormatter`. - * @details The long era symbols for the receiver. An array containing 'NSString' objects representing the era symbols for the receiver (for example, {"Before Common Era", "Common Era"}). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_long_era_symbols(const std::vector& value) const; /** * @brief Returns the `monthSymbols` property of `NSDateFormatter`. - * @details The month symbols for the receiver. * @return The converted Objective-C result. */ std::vector month_symbols() const; /** * @brief Sets the `monthSymbols` property of `NSDateFormatter`. - * @details The month symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_month_symbols(const std::vector& value) const; /** * @brief Returns the `quarterSymbols` property of `NSDateFormatter`. - * @details The quarter symbols for the receiver. * @return The converted Objective-C result. */ std::vector quarter_symbols() const; /** * @brief Sets the `quarterSymbols` property of `NSDateFormatter`. - * @details The quarter symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_quarter_symbols(const std::vector& value) const; /** * @brief Returns the `shortMonthSymbols` property of `NSDateFormatter`. - * @details The array of short month symbols for the receiver. * @return The converted Objective-C result. */ std::vector short_month_symbols() const; /** * @brief Sets the `shortMonthSymbols` property of `NSDateFormatter`. - * @details The array of short month symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_short_month_symbols(const std::vector& value) const; /** * @brief Returns the `shortQuarterSymbols` property of `NSDateFormatter`. - * @details The short quarter symbols for the receiver. * @return The converted Objective-C result. */ std::vector short_quarter_symbols() const; /** * @brief Sets the `shortQuarterSymbols` property of `NSDateFormatter`. - * @details The short quarter symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_short_quarter_symbols(const std::vector& value) const; /** * @brief Returns the `shortStandaloneMonthSymbols` property of `NSDateFormatter`. - * @details The short standalone month symbols for the receiver. * @return The converted Objective-C result. */ std::vector short_standalone_month_symbols() const; /** * @brief Sets the `shortStandaloneMonthSymbols` property of `NSDateFormatter`. - * @details The short standalone month symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_short_standalone_month_symbols(const std::vector& value) const; /** * @brief Returns the `shortStandaloneQuarterSymbols` property of `NSDateFormatter`. - * @details The short standalone quarter symbols for the receiver. * @return The converted Objective-C result. */ std::vector short_standalone_quarter_symbols() const; /** * @brief Sets the `shortStandaloneQuarterSymbols` property of `NSDateFormatter`. - * @details The short standalone quarter symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_short_standalone_quarter_symbols(const std::vector& value) const; /** * @brief Returns the `shortStandaloneWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of short standalone weekday symbols for the receiver. * @return The converted Objective-C result. */ std::vector short_standalone_weekday_symbols() const; /** * @brief Sets the `shortStandaloneWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of short standalone weekday symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_short_standalone_weekday_symbols(const std::vector& value) const; /** * @brief Returns the `shortWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of short weekday symbols for the receiver. * @return The converted Objective-C result. */ std::vector short_weekday_symbols() const; /** * @brief Sets the `shortWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of short weekday symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_short_weekday_symbols(const std::vector& value) const; /** * @brief Returns the `standaloneMonthSymbols` property of `NSDateFormatter`. - * @details The standalone month symbols for the receiver. * @return The converted Objective-C result. */ std::vector standalone_month_symbols() const; /** * @brief Sets the `standaloneMonthSymbols` property of `NSDateFormatter`. - * @details The standalone month symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standalone_month_symbols(const std::vector& value) const; /** * @brief Returns the `standaloneQuarterSymbols` property of `NSDateFormatter`. - * @details The standalone quarter symbols for the receiver. * @return The converted Objective-C result. */ std::vector standalone_quarter_symbols() const; /** * @brief Sets the `standaloneQuarterSymbols` property of `NSDateFormatter`. - * @details The standalone quarter symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standalone_quarter_symbols(const std::vector& value) const; /** * @brief Returns the `standaloneWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of standalone weekday symbols for the receiver. * @return The converted Objective-C result. */ std::vector standalone_weekday_symbols() const; /** * @brief Sets the `standaloneWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of standalone weekday symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standalone_weekday_symbols(const std::vector& value) const; /** * @brief Returns the `timeStyle` property of `NSDateFormatter`. - * @details The time style of the receiver. * @return The converted Objective-C result. */ DateFormatterStyle time_style() const; /** * @brief Sets the `timeStyle` property of `NSDateFormatter`. - * @details The time style of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_time_style(DateFormatterStyle value) const; /** * @brief Returns the `timeZone` property of `NSDateFormatter`. - * @details The time zone for the receiver. If unspecified, the system time zone is used. * @return The converted Objective-C result. */ TimeZone time_zone() const; /** * @brief Sets the `timeZone` property of `NSDateFormatter`. - * @details The time zone for the receiver. If unspecified, the system time zone is used. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_time_zone(const TimeZone& value) const; /** * @brief Returns the `twoDigitStartDate` property of `NSDateFormatter`. - * @details The earliest date that can be denoted by a two-digit year specifier. If the two-digit start date is set to January 6, 1976, then "January 1, 76" is interpreted as New Year's Day in 2076, whereas "February 14, 76" is interpreted as Valentine's Day in 1976. By default, this property is equal to December 31, 1949. * @return The converted Objective-C result. */ Date two_digit_start_date() const; /** * @brief Sets the `twoDigitStartDate` property of `NSDateFormatter`. - * @details The earliest date that can be denoted by a two-digit year specifier. If the two-digit start date is set to January 6, 1976, then "January 1, 76" is interpreted as New Year's Day in 2076, whereas "February 14, 76" is interpreted as Valentine's Day in 1976. By default, this property is equal to December 31, 1949. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_two_digit_start_date(const Date& value) const; /** * @brief Returns the `veryShortMonthSymbols` property of `NSDateFormatter`. - * @details The very short month symbols for the receiver. * @return The converted Objective-C result. */ std::vector very_short_month_symbols() const; /** * @brief Sets the `veryShortMonthSymbols` property of `NSDateFormatter`. - * @details The very short month symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_very_short_month_symbols(const std::vector& value) const; /** * @brief Returns the `veryShortStandaloneMonthSymbols` property of `NSDateFormatter`. - * @details The very short month symbols for the receiver. * @return The converted Objective-C result. */ std::vector very_short_standalone_month_symbols() const; /** * @brief Sets the `veryShortStandaloneMonthSymbols` property of `NSDateFormatter`. - * @details The very short month symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_very_short_standalone_month_symbols(const std::vector& value) const; /** * @brief Returns the `veryShortStandaloneWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of very short standalone weekday symbols for the receiver. * @return The converted Objective-C result. */ std::vector very_short_standalone_weekday_symbols() const; /** * @brief Sets the `veryShortStandaloneWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of very short standalone weekday symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_very_short_standalone_weekday_symbols(const std::vector& value) const; /** * @brief Returns the `veryShortWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of very short weekday symbols for the receiver. * @return The converted Objective-C result. */ std::vector very_short_weekday_symbols() const; /** * @brief Sets the `veryShortWeekdaySymbols` property of `NSDateFormatter`. - * @details The array of very short weekday symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_very_short_weekday_symbols(const std::vector& value) const; /** * @brief Returns the `weekdaySymbols` property of `NSDateFormatter`. - * @details The array of weekday symbols for the receiver. * @return The converted Objective-C result. */ std::vector weekday_symbols() const; /** * @brief Sets the `weekdaySymbols` property of `NSDateFormatter`. - * @details The array of weekday symbols for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_weekday_symbols(const std::vector& value) const; diff --git a/include/generated/date_interval.h b/include/generated/date_interval.h index 1eab910b..0ac055dd 100644 --- a/include/generated/date_interval.h +++ b/include/generated/date_interval.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDateInterval` (Foundation). - * @details An object representing the span of time between a specific start date and end date. In Swift, this object bridges to ''DateInterval''; use ''NSDateInterval'' when you need reference semantics or other Foundation-specific behavior. An 'NSDateInterval' object represents a closed interval between two dates. The 'NSDateInterval' class provides a programmatic interface for calculating the duration of a time interval and determining whether a date falls within it, as well as comparing date intervals and checking to see whether they intersect. An 'NSDateInterval' object consists of a ''startDate'' and an ''endDate''. The ''startDate'' and ''endDate'' of a date interval can be equal, in which case its ''duration'' is '0'. However, ''endDate'' cannot occur earlier than ''startDate''. You can use the ''DateIntervalFormatter'' class to create string representations of 'NSDateInterval' objects that are suitable for display in the current locale. > Important: > The Swift overlay to the Foundation framework provides the ''DateInterval'' structure, which bridges to the 'NSDateInterval' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,54 +46,49 @@ namespace cocoon explicit DateInterval(Adopt adopt); /** * @brief Calls `-[NSDateInterval compare:]`. - * @details If both the start dates and the durations are equal, then the intervals are considered equal and 'NSOrderedSame' is returned as the result. - Parameters: - dateInterval: The date interval with which to compare the receiver. - Returns: An 'NSComparisonResult' value that indicates the temporal ordering of the receiver and the given date interval: 'NSOrderedAscending' if the receiver's start date occurs earlier, or both start dates are equal and the receiver's duration is less. 'NSOrderedDescending' if the receiver's start date occurs later, or both start dates are equal and the receiver's duration is greater. 'NSOrderedSame' if the start dates and durations are equal. + * @details (NSComparisonResult)compare:(NSDateInterval ) prioritizes ordering by start date. If the start dates are equal, then it will order by duration. e.g. Given intervals a and b a. |-----| b. |-----| [a compare:b] would return NSOrderedAscending because a's startDate is earlier in time than b's start date. In the event that the start dates are equal, the compare method will attempt to order by duration. e.g. Given intervals c and d c. |-----| d. |---| [c compare:d] would result in NSOrderedDescending because c is longer than d. If both the start dates and the durations are equal, then the intervals are considered equal and NSOrderedSame is returned as the result. * @param date_interval Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ComparisonResult compare(const DateInterval& date_interval) const; /** * @brief Calls `-[NSDateInterval containsDate:]`. - * @details Indicates whether the receiver contains the specified date. - Parameters: - date: The date for which to test membership of the date interval. - Returns: 'YES' if the receiver contains 'date'. Otherwise, 'NO'. * @param date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool contains_date(const Date& date) const; /** * @brief Calls `-[NSDateInterval intersectionWithDateInterval:]`. - * @details Returns the intersection between the receiver and the specified date interval. - Parameters: - dateInterval: The date interval with which to calculate the intersection of the receiver. - Returns: A date interval for the intersection of the receiver and 'dateInterval', or 'nil' if no intersection occurs. Calculating the intersection of date intervals is a commutative and associative operation. The intersection of a date interval with itself is equal to itself. + * @details This method returns an NSDateInterval object that represents the interval where the given date interval and the current instance intersect. In the event that there is no intersection, the method returns nil. * @param date_interval Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DateInterval intersection_with_date_interval(const DateInterval& date_interval) const; /** * @brief Calls `-[NSDateInterval intersectsDateInterval:]`. - * @details Indicates whether the receiver intersects with the specified date interval. - Parameters: - dateInterval: The date interval with which to check the receiver for intersection. * @param date_interval Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool intersects_date_interval(const DateInterval& date_interval) const; /** * @brief Calls `-[NSDateInterval isEqualToDateInterval:]`. - * @details Indicates whether the receiver is equal to the specified date interval. - Parameters: - dateInterval: The date interval with which to check the receiver for equality. - Returns: 'YES' if the start date and duration of 'dateInterval' and the receiver are equal. Otherwise, 'NO'. * @param date_interval Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equal_to_date_interval(const DateInterval& date_interval) const; /** * @brief Returns the `duration` property of `NSDateInterval`. - * @details The duration of the date interval. * @return The converted Objective-C result. */ double duration() const; /** * @brief Returns the `endDate` property of `NSDateInterval`. - * @details The end date of the date interval. * @return The converted Objective-C result. */ Date end_date() const; /** * @brief Returns the `startDate` property of `NSDateInterval`. - * @details The start date of the date interval. + * @details NSDateInterval represents a closed date interval in the form of [startDate, endDate]. It is possible for the start and end dates to be the same with a duration of 0. NSDateInterval does not support reverse intervals i.e. intervals where the duration is less than 0 and the end date occurs earlier in time than the start date. * @return The converted Objective-C result. */ Date start_date() const; diff --git a/include/generated/date_interval_formatter.h b/include/generated/date_interval_formatter.h index 4207d2f0..29596bc9 100644 --- a/include/generated/date_interval_formatter.h +++ b/include/generated/date_interval_formatter.h @@ -16,7 +16,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDateIntervalFormatter` (Foundation). - * @details A formatter that creates string representations of time intervals. A ''DateIntervalFormatter'' object creates user-readable strings from pairs of dates. Use a date interval formatter to create user-readable strings of the form \\\ '-' \\\ for your app's interface, where \\\ and \\\ are date values that you supply. The formatter uses locale and language information, along with custom formatting options, to define the content of the resulting string. You can specify different styles for the date and time information in each date value. To use this class, create an instance, configure its properties, and call the ''string(from:to:)'' method to generate a string. The properties of this class let you configure the calendar and specify the style to apply to date and time values. Given a current date of January 16, 2015, Configuring the Formatter Options shows how to configure a formatter object and generate the string "1/16/15 - 1/17/15". Configuring a formatter object \@TabNavigator { \@Tab("Swift") { '''swift let formatter = DateIntervalFormatter() formatter.dateStyle = .short formatter.timeStyle = .none // Create two dates that are exactly 1 day apart. let startDate = Date() let endDate = Date(timeInterval: 86400, since: startDate) // Use the configured formatter to generate the string. let outputString = formatter.string(from: startDate, to: endDate) ''' } \@Tab("Objective-C") { '''objc NSDateIntervalFormatter formatter = [[NSDateIntervalFormatter alloc] init]; formatter.dateStyle = NSDateIntervalFormatterShortStyle; formatter.timeStyle = NSDateIntervalFormatterNoStyle; // Create two dates that are exactly 1 day apart. NSDate startDate = [NSDate date]; NSDate endDate = [NSDate dateWithTimeInterval:86400 sinceDate:startDate]; // Use the configured formatter to generate the string. NSString outputString = [formatter stringFromDate:startDate toDate:endDate]; ''' } } > Note: > Always set to the ''dateStyle'' and ''timeStyle'' properties to appropriate values before generating any strings. The ''string(from:to:)'' method may be called safely from any thread of your app. It is also safe to share a single instance of this class from multiple threads, with the caveat that you should not change the configuration of the object while another thread is using it to generate a string. > Tip: > In Swift, you can use ''Date/IntervalFormatStyle'' rather than ''DateIntervalFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -54,7 +53,7 @@ namespace cocoon explicit DateIntervalFormatter(Adopt adopt); /** * @brief Calls `-[NSDateIntervalFormatter stringFromDate:toDate:]`. - * @details Returns a formatted date interval from the specified start date to end date. If the range is smaller than the resolution specified by the 'dateTemplate', a single date format will be produced. If the range is larger than the format specified by the 'dateTemplate', a locale-specific fallback will be used to format the items missing from the pattern. For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours) - The pattern 'jm' will produce for 'en_US', "7:56 AM - 7:56 PM" for 'en_GB', "7:56 - 19:56" - The pattern 'MMMd' will produce for 'en_US', "Mar 4" for 'en_GB', "4 Mar" If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes) - The pattern 'jm' will produce for 'en_US', "3/4/2010 7:56 AM - 3/8/2010 4:11 PM" for 'en_GB', "4/3/2010 7:56 - 8/3/2010 16:11" - The pattern 'MMMd' will produce for 'en_US', "Mar 4-8" for 'en_GB', "4-8 Mar" + * @details If the range smaller than the resolution specified by the dateTemplate, a single date format will be produced. If the range is larger than the format specified by the dateTemplate, a locale-specific fallback will be used to format the items missing from the pattern. For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours) - The pattern jm will produce for en_US, "7:56 AM - 7:56 PM" for en_GB, "7:56 - 19:56" - The pattern MMMd will produce for en_US, "Mar 4" for en_GB, "4 Mar" If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes) - The pattern jm will produce for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM" for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11" - The pattern MMMd will produce for en_US, "Mar 4-8" for en_GB, "4-8 Mar" * @param from_date Argument converted to the Objective-C parameter of the same role. * @param to_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -62,80 +61,67 @@ namespace cocoon std::string string_from_date(const Date& from_date, const Date& to_date) const; /** * @brief Calls `-[NSDateIntervalFormatter stringFromDateInterval:]`. - * @details Returns a formatted string for the given date interval. * @param date_interval Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_date_interval(const DateInterval& date_interval) const; /** * @brief Returns the `calendar` property of `NSDateIntervalFormatter`. - * @details The calendar for the formatter. Default is the calendar of the locale. * @return The converted Objective-C result. */ Calendar calendar() const; /** * @brief Sets the `calendar` property of `NSDateIntervalFormatter`. - * @details The calendar for the formatter. Default is the calendar of the locale. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_calendar(const Calendar& value) const; /** * @brief Returns the `dateStyle` property of `NSDateIntervalFormatter`. - * @details The date style for the formatter. Default is 'NSDateIntervalFormatterNoStyle'. * @return The converted Objective-C result. */ DateIntervalFormatterStyle date_style() const; /** * @brief Sets the `dateStyle` property of `NSDateIntervalFormatter`. - * @details The date style for the formatter. Default is 'NSDateIntervalFormatterNoStyle'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_date_style(DateIntervalFormatterStyle value) const; /** * @brief Returns the `dateTemplate` property of `NSDateIntervalFormatter`. - * @details The date template for the formatter. Default is an empty string. * @return The converted Objective-C result. */ std::string date_template() const; /** * @brief Sets the `dateTemplate` property of `NSDateIntervalFormatter`. - * @details The date template for the formatter. Default is an empty string. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_date_template(const std::string& value) const; /** * @brief Returns the `locale` property of `NSDateIntervalFormatter`. - * @details The locale for the formatter. Default is '[NSLocale currentLocale]'. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSDateIntervalFormatter`. - * @details The locale for the formatter. Default is '[NSLocale currentLocale]'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; /** * @brief Returns the `timeStyle` property of `NSDateIntervalFormatter`. - * @details The time style for the formatter. Default is 'NSDateIntervalFormatterNoStyle'. * @return The converted Objective-C result. */ DateIntervalFormatterStyle time_style() const; /** * @brief Sets the `timeStyle` property of `NSDateIntervalFormatter`. - * @details The time style for the formatter. Default is 'NSDateIntervalFormatterNoStyle'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_time_style(DateIntervalFormatterStyle value) const; /** * @brief Returns the `timeZone` property of `NSDateIntervalFormatter`. - * @details The time zone for the formatter. Default is '[NSTimeZone defaultTimeZone]'. * @return The converted Objective-C result. */ TimeZone time_zone() const; /** * @brief Sets the `timeZone` property of `NSDateIntervalFormatter`. - * @details The time zone for the formatter. Default is '[NSTimeZone defaultTimeZone]'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_time_zone(const TimeZone& value) const; diff --git a/include/generated/decimal_number.h b/include/generated/decimal_number.h index 5f907ddc..83d9bbde 100644 --- a/include/generated/decimal_number.h +++ b/include/generated/decimal_number.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDecimalNumber` (Foundation). - * @details An object for representing and performing arithmetic on base-10 numbers. In Swift, this object bridges to ''Decimal''; use ''NSDecimalNumber'' when you need reference semantics or other Foundation-specific behavior. 'NSDecimalNumber', an immutable subclass of 'NSNumber', provides an object-oriented wrapper for doing base-10 arithmetic. An instance can represent any number that can be expressed as 'mantissa x 10^exponent' where mantissa is a decimal integer up to 38 digits long, and exponent is an integer from –128 through 127. > Important: > The Swift overlay to the Foundation framework provides the ''Decimal'' structure, which bridges to the ''NSDecimalNumber'' class. For more information about value types, see \. + * @details NSDecimalNumber: the class * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Number. * @@ -57,21 +57,18 @@ namespace cocoon using Value::obj_c_type; /** * @brief Calls `-[NSDecimalNumber compare:]`. - * @details Compares this decimal number to another number. - Parameter decimalNumber: The number to compare. This value must not be 'nil'. - Returns: 'NSOrderedAscending' if the value of 'decimalNumber' is greater than the receiver, 'NSOrderedSame' if they're equal, and 'NSOrderedDescending' if 'decimalNumber' is less. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ComparisonResult compare(const Number& decimal_number) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByAdding:]`. - * @details Adds this number to another given number. - Parameter decimalNumber: The number to add to the receiver. - Returns: A new 'NSDecimalNumber' object whose value is the sum of the receiver and 'decimalNumber'. This method uses the default behavior when handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DecimalNumber decimal_number_by_adding(const DecimalNumber& decimal_number) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByAdding:withBehavior:]`. - * @details Adds this number to another given number using the specified behavior. - Parameters: - decimalNumber: The number to add to the receiver. - behavior: The behavior for handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @param behavior Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -79,14 +76,12 @@ namespace cocoon DecimalNumber decimal_number_by_adding(const DecimalNumber& decimal_number, const Object& behavior) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByDividingBy:]`. - * @details Divides the number by another given number. - Parameter decimalNumber: The number by which to divide the receiver. - Returns: A new 'NSDecimalNumber' object whose value is the value of the receiver divided by 'decimalNumber'. This method uses the default behavior when handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DecimalNumber decimal_number_by_dividing_by(const DecimalNumber& decimal_number) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByDividingBy:withBehavior:]`. - * @details Divides the number by another given number using the specified behavior. - Parameters: - decimalNumber: The number by which to divide the receiver. - behavior: The behavior for handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @param behavior Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -94,14 +89,12 @@ namespace cocoon DecimalNumber decimal_number_by_dividing_by(const DecimalNumber& decimal_number, const Object& behavior) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByMultiplyingBy:]`. - * @details Multiplies the number by another given number. - Parameter decimalNumber: The number by which to multiply the receiver. - Returns: A new 'NSDecimalNumber' object whose value is the receiver multiplied by 'decimalNumber'. This method uses the default behavior when handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DecimalNumber decimal_number_by_multiplying_by(const DecimalNumber& decimal_number) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByMultiplyingBy:withBehavior:]`. - * @details Multiplies the number by another given number using the specified behavior. - Parameters: - decimalNumber: The number by which to multiply the receiver. - behavior: The behavior for handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @param behavior Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -109,14 +102,12 @@ namespace cocoon DecimalNumber decimal_number_by_multiplying_by(const DecimalNumber& decimal_number, const Object& behavior) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByMultiplyingByPowerOf10:]`. - * @details Multiplies the number by 10 raised to the given power. This method uses the default behavior when handling calculation errors and rounding. * @param power Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DecimalNumber decimal_number_by_multiplying_by_power_of10(std::int16_t power) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByMultiplyingByPowerOf10:withBehavior:]`. - * @details Multiplies the number by 10 raised to the given power using the specified behavior. * @param power Argument converted to the Objective-C parameter of the same role. * @param behavior Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -124,14 +115,12 @@ namespace cocoon DecimalNumber decimal_number_by_multiplying_by_power_of10(std::int16_t power, const Object& behavior) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByRaisingToPower:]`. - * @details Raises the number to a given power. - Parameter power: The power to which to raise the receiver. - Returns: A new 'NSDecimalNumber' object whose value is the value of the receiver raised to the power 'power'. This method uses the default behavior when handling calculation errors and rounding. * @param power Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DecimalNumber decimal_number_by_raising_to_power(std::uint64_t power) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByRaisingToPower:withBehavior:]`. - * @details Raises the number to a given power using the specified behavior. - Parameters: - power: The power to which to raise the receiver. - behavior: The behavior for handling calculation errors and rounding. * @param power Argument converted to the Objective-C parameter of the same role. * @param behavior Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -139,21 +128,18 @@ namespace cocoon DecimalNumber decimal_number_by_raising_to_power(std::uint64_t power, const Object& behavior) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberByRoundingAccordingToBehavior:]`. - * @details Returns a rounded version of the decimal number using the specified rounding behavior. - Parameter behavior: The rounding behavior to apply. The scale of the behavior determines the number of digits a rounded value is allowed to have after the decimal separator. * @param behavior Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DecimalNumber decimal_number_by_rounding_according_to_behavior(const Object& behavior) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberBySubtracting:]`. - * @details Subtracts another given number from this one. - Parameter decimalNumber: The number to subtract from the receiver. - Returns: A new 'NSDecimalNumber' object whose value is the receiver minus 'decimalNumber'. This method uses the default behavior when handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DecimalNumber decimal_number_by_subtracting(const DecimalNumber& decimal_number) const; /** * @brief Calls `-[NSDecimalNumber decimalNumberBySubtracting:withBehavior:]`. - * @details Subtracts another given number from this one using the specified behavior. - Parameters: - decimalNumber: The number to subtract from the receiver. - behavior: The behavior for handling calculation errors and rounding. * @param decimal_number Argument converted to the Objective-C parameter of the same role. * @param behavior Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -161,68 +147,57 @@ namespace cocoon DecimalNumber decimal_number_by_subtracting(const DecimalNumber& decimal_number, const Object& behavior) const; /** * @brief Calls `-[NSDecimalNumber descriptionWithLocale:]`. - * @details Returns a string that represents the contents of the decimal number for a given locale. - Parameter locale: An object containing locale information with which to format the description. - Returns: A string that represents the contents of the decimal number formatted using the locale information in 'locale'. * @param locale Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string description_with_locale(const Object& locale) const; /** * @brief Returns the `decimalValue` property of `NSDecimalNumber`. - * @details The decimal value of the number. * @return The converted Objective-C result. */ Decimal decimal_value() const; /** * @brief Returns the `defaultBehavior` property of `NSDecimalNumber`. - * @details The way arithmetic methods round off and handle error conditions. By default, the arithmetic methods use the ''NSDecimalNumberHandler/defaultDecimalNumberHandler'' behavior: 'NSRoundPlain' rounding, assuming precision does not exceed 38 significant digits, and raising exceptions on overflow, underflow, and divide by zero. If this default behavior doesn't suit your application, you should use methods that let you specify the behavior, like ''adding(:withBehavior:)''. If you find yourself using a particular behavior consistently, you can specify a different default behavior with 'setDefaultBehavior(:)'. The default behavior is maintained separately for each thread in your app. * @return The converted Objective-C result. */ static Object default_behavior(); /** * @brief Sets the `defaultBehavior` property of `NSDecimalNumber`. - * @details The way arithmetic methods round off and handle error conditions. By default, the arithmetic methods use the ''NSDecimalNumberHandler/defaultDecimalNumberHandler'' behavior: 'NSRoundPlain' rounding, assuming precision does not exceed 38 significant digits, and raising exceptions on overflow, underflow, and divide by zero. If this default behavior doesn't suit your application, you should use methods that let you specify the behavior, like ''adding(:withBehavior:)''. If you find yourself using a particular behavior consistently, you can specify a different default behavior with 'setDefaultBehavior(:)'. The default behavior is maintained separately for each thread in your app. * @param value Argument converted to the Objective-C parameter of the same role. */ static void set_default_behavior(const Object& value); /** * @brief Returns the `doubleValue` property of `NSDecimalNumber`. - * @details An approximate 'double' value for the decimal number. * @return The converted Objective-C result. */ double double_value() const; /** * @brief Returns the `maximumDecimalNumber` property of `NSDecimalNumber`. - * @details The largest possible value of a decimal number. * @return The converted Objective-C result. */ static DecimalNumber maximum_decimal_number(); /** * @brief Returns the `minimumDecimalNumber` property of `NSDecimalNumber`. - * @details The smallest possible value of a decimal number. * @return The converted Objective-C result. */ static DecimalNumber minimum_decimal_number(); /** * @brief Returns the `notANumber` property of `NSDecimalNumber`. - * @details A decimal number that specifies no number. Any arithmetic method receiving 'notANumber' as an argument returns 'notANumber'. * @return The converted Objective-C result. */ static DecimalNumber not_a_number(); /** * @brief Returns the `objCType` property of `NSDecimalNumber`. - * @details A C string containing the Objective-C type of the data contained in the decimal number object. Returns '"d"' (for 'double'). * @return The converted Objective-C result. */ std::string obj_c_type() const; /** * @brief Returns the `one` property of `NSDecimalNumber`. - * @details A decimal number equivalent to the number 1. * @return The converted Objective-C result. */ static DecimalNumber one(); /** * @brief Returns the `zero` property of `NSDecimalNumber`. - * @details A decimal number equivalent to the number 0. * @return The converted Objective-C result. */ static DecimalNumber zero(); diff --git a/include/generated/decimal_number_handler.h b/include/generated/decimal_number_handler.h index 4091e1ec..a3144e16 100644 --- a/include/generated/decimal_number_handler.h +++ b/include/generated/decimal_number_handler.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSDecimalNumberHandler` (Foundation). - * @details A class that adopts the decimal number behaviors protocol. This class allows you to set the way an ''NSDecimalNumber'' object rounds off and handles errors, without having to create a custom class. You can use an instance of this class as an argument to any of the ''NSDecimalNumber'' methods that end with '...Behavior:'. If you don't think you need special behavior, you probably don't need this class—it is likely that ''NSDecimalNumber'''s default behavior will suit your needs. For more information, see the ''NSDecimalNumberBehaviors'' protocol specification. + * @details A class for defining common behaviors * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -34,7 +34,6 @@ namespace cocoon explicit DecimalNumberHandler(Adopt adopt); /** * @brief Returns the `defaultDecimalNumberHandler` property of `NSDecimalNumberHandler`. - * @details Returns the default instance of 'NSDecimalNumberHandler'. The default handler rounds to closest possible return value (''NSRoundPlain''), assumes precision up to 38 significant digits, and raises on overflow, underflow, and divide by zero. * @return The converted Objective-C result. */ static DecimalNumberHandler default_decimal_number_handler(); diff --git a/include/generated/delete_command.h b/include/generated/delete_command.h index 84af6ba3..a7fa2e1b 100644 --- a/include/generated/delete_command.h +++ b/include/generated/delete_command.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDeleteCommand` (Foundation). - * @details A command that deletes a scriptable object. An instance of 'NSDeleteCommand' deletes the specified scriptable object or objects (such as words, paragraphs, and so on). Suppose, for example, a user executes a script that sends the command 'delete the third rectangle in the first document' to the Sketch sample application (located in '/Developer/Examples/AppKit'). Cocoa creates an 'NSDeleteCommand' object to perform the operation. When the command is executed, it uses the key-value coding mechanism (by invoking 'removeValueAtIndex:fromPropertyWithKey:') to remove the specified object or objects from their container. See the description for \ for related information. 'NSDeleteCommand' is part of Cocoa's built-in scripting support. Most applications don't need to subclass 'NSDeleteCommand' or call its methods. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptCommand. * @@ -43,13 +42,11 @@ namespace cocoon using ScriptCommand::set_receivers_specifier; /** * @brief Calls `-[NSDeleteCommand setReceiversSpecifier:]`. - * @details Splits off the inner-most child specifier from the receivers specifier. * @param receivers_ref Argument converted to the Objective-C parameter of the same role. */ void set_receivers_specifier(const ScriptObjectSpecifier& receivers_ref) const; /** * @brief Returns the `keySpecifier` property of `NSDeleteCommand`. - * @details The key specifier for the delete operation. * @return The converted Objective-C result. */ ScriptObjectSpecifier key_specifier() const; diff --git a/include/generated/dimension.h b/include/generated/dimension.h index a244c291..f0a7a208 100644 --- a/include/generated/dimension.h +++ b/include/generated/dimension.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDimension` (Foundation). - * @details An abstract class representing a dimensional unit of measure. The Foundation framework provides concrete subclasses for many of the most common types of physical units. Table 1: ''Dimension'' subclasses. | NSDimension subclass | Description | Base unit | |---|---|---| | ''UnitAcceleration'' | Unit of measure for acceleration | meters per second squared (m/s²) | | ''UnitAngle'' | Unit of measure for planar angle and rotation | degrees (°) | | ''UnitArea'' | Unit of measure for area | square meters (m²) | | ''UnitConcentrationMass'' | Unit of measure for concentration of mass | grams per liter (g/L) | | ''UnitDispersion'' | Unit of measure for dispersion | parts per million (ppm) | | ''UnitDuration'' | Unit of measure for duration of time | seconds (sec) | | ''UnitElectricCharge'' | Unit of measure for electric charge | coulombs (C) | | ''UnitElectricCurrent'' | Unit of measure for electric current | amperes (A) | | ''UnitElectricPotentialDifference'' | Unit of measure for electric potential difference | volts (V) | | ''UnitElectricResistance'' | Unit of measure for electric resistance | ohms (Ω) | | ''UnitEnergy'' | Unit of measure for energy | joules (J) | | ''UnitFrequency'' | Unit of measure for frequency | hertz (Hz) | | ''UnitFuelEfficiency'' | Unit of measure for fuel efficiency | liters per 100 kilometers (L/100km) | | ''UnitIlluminance'' | Unit of measure for illuminance | lux (lx) | | ''UnitInformationStorage'' | Unit of measure for quantities of information | bytes (b) | | ''UnitLength'' | Unit of measure for length | meters (m) | | ''UnitMass'' | Unit of measure for mass | kilograms (kg) | | ''UnitPower'' | Unit of measure for power | watts (W) | | ''UnitPressure'' | Unit of measure for pressure | newtons per square meter (N/m²) | | ''UnitSpeed'' | Unit of measure for speed | meters per second (m/s) | | ''UnitTemperature'' | Unit of measure for temperature | kelvin (K) | | ''UnitVolume'' | Unit of measure for volume | liters (L) | Each instance of a ''Dimension'' subclass has a ''converter'', which represents the unit in terms of the dimension's ''baseUnit()''. For example, the 'NSLengthUnit' class uses ''UnitLength/meters'' as its base unit. The system defines the predefined ''UnitLength/miles'' unit by a ''UnitConverterLinear'' with a ''UnitConverterLinear/coefficient'' of '1609.34', which corresponds to the conversion ratio of miles to meters (1 mi = 1609.34 m); the system defines the predefined ''UnitLength/meters'' unit by a ''UnitConverterLinear'' with a ''UnitConverterLinear/coefficient'' of '1.0' because it's the base unit. You typically use an 'NSDimension' subclass in conjunction with the ''NSMeasurement'' class to represent specific quantities of a particular unit. \#\#\# Working with Custom Units In addition to the Apple-provided units, you can define custom units. You can initialize custom units from a symbol and converter of an existing type or implemented as a class method of an existing type for additional convenience. You can also define your own 'NSDimension' subclass to represent an entirely new unit dimension. \#\#\#\# Initializing a Custom Unit with a Specified Symbol and Definition The simplest way to define a custom unit is to create a new instance of an existing 'NSDimension' subclass using the ''init(symbol:converter:)'' method. For example, the smoot is a nonstandard unit of length (1 smoot = 1.70180 m). You can create a new instance of ''UnitLength'' as follows: \@TabNavigator { \@Tab("Swift") { '''swift let smoots = UnitLength(symbol: "smoot", converter: UnitConverterLinear(coefficient: 1.70180)) ''' } \@Tab("Objective-C") { '''objc NSUnitConverter smootsToMeters = [[NSUnitConverterLinear alloc] initWithCoefficient:1.70180]; NSUnitLength smoots = [[NSUnitLength alloc] initWithSymbol:\@"smoot" converter:smootsToMeters]; ''' } } \#\#\#\# Extending Existing Dimension Subclasses Alternatively, if you use a custom unit extensively throughout an app, consider extending the corresponding ''Dimension'' subclass and adding a static variable. For example, a measurement of speed can be furlongs per fortnight (1 fur/ftn = 201.168 m / 1,209,600 s). If an app makes frequent use of this unit, you can extend ''UnitSpeed'' to add a 'furlongsPerFortnight' static variable for convenient access as follows: \@TabNavigator { \@Tab("Swift") { '''swift extension UnitSpeed { static let furlongPerFortnight = UnitSpeed(symbol: "fur/ftn", converter: UnitConverterLinear(coefficient: 201.168 / 1209600.0)) } ''' } \@Tab("Objective-C") { '''objc \@interface NSUnitSpeed () + (NSUnitSpeed )furlongsPerFortnight; \@end \@implementation NSUnitSpeed () + (NSUnitSpeed )furlongsPerFortnight { NSUnitConverter furlongsPerFortnightToMetersPerSecond = [[NSUnitConverterLinear alloc] initWithCoefficient:201.168 / 1209600.0]; return [[NSUnitSpeed alloc] initWithSymbol:\@"fur/ftn" converter:furlongsPerFortnightToMetersPerSecond]; } \@end ''' } } \#\#\#\# Creating a Custom Dimension Subclass You can create a new subclass of ''Dimension'' to describe a new unit dimension. For example, the Foundation framework doesn't define any units for radioactivity. Radioactivity is the process by which the nucleus of an atom emits radiation. The SI unit of measure for radioactivity is the becquerel (Bq), which is the quantity of radioactive material in which one nucleus decays per second (1 Bq = 1 s-1). Radioactivity is also commonly described in terms of curies (Ci), a unit defined relative to the decay of one gram of the radium-226 isotope (1 Ci = 3.7 × 1010 Bq). You can implement a 'CustomUnitRadioactivity' class that defines both units of radioactivity as follows: \@TabNavigator { \@Tab("Swift") { '''swift class CustomRadioactivityUnit: Dimension { static let becquerel = CustomRadioactivityUnit(symbol: "Bq", UnitConverterLinear(coefficient: 1.0)) static let curie = CustomRadioactivityUnit(symbol: "Ci", UnitConverterLinear(coefficient: 3.7e10)) static let baseUnit = self.becquerel } ''' } \@Tab("Objective-C") { '''objc \@interface CustomUnitRadioactivity: NSDimension + (CustomUnitRadioactivity )becquerels; + (CustomUnitRadioactivity )curies; \@end \@implementation CustomRadioactivityUnit + (CustomUnitRadioactivity )becquerels { NSUnitConverter baseUnitConverter = [[NSUnitConverterLinear alloc] initWithCoefficient:1]; return [[CustomUnitRadioactivity alloc] initWithSymbol:\@"Bq" converter:baseUnitConverter]; } + (CustomUnitRadioactivity )curies { NSUnitConverter curiesToBecquerels = [[NSUnitConverterLinear alloc] initWithCoefficient:3.7e10]; return [[CustomUnitRadioactivity alloc] initWithSymbol:\@"Ci" converter:curiesToBecquerels]; } + (instancetype)baseUnit { return [self bacquerels]; } \@end ''' } } \#\#\# Subclassing Notes The system provides ''Dimension'' for subclassing. Although the subclasses listed in Table 1 above are suitable for most purposes, you may want to define a custom unit type. For instance, you may need a custom unit type to represent a derived unit, such as magnetic flux (measured as the product of electric potential difference and time). To represent dimensionless units, subclass ''Unit'' directly. \#\#\#\# Methods to Override All subclasses must fully implement the ''baseUnit()'' method designating the base unit, relative to which you define any additional units. You must also implement a class method named for the base unit itself, to use interchangeably. For example, the ''UnitIlluminance'' class defines its ''baseUnit()'' in terms of the lux (lx) and provides a corresponding ''UnitIlluminance/lux'' class method. \#\#\#\# Alternatives to Subclassing As described in \, you need to create a custom subclass of ''Dimension'' only if you or the system haven't defined a unit of the desired dimension. You can define a custom unit for an existing ''Dimension'' subclass by either calling the ''init(symbol:converter:)'' method or extending the subclass and adding a corresponding class method. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Unit. * @@ -43,13 +42,12 @@ namespace cocoon explicit Dimension(Adopt adopt); /** * @brief Calls `+[NSDimension baseUnit]`. - * @details Returns the base unit of the dimension. The default implementation returns 'nil' to indicate that the 'NSDimension' class should not be used directly. When implementing a subclass, you should return a unit converter that returns the inputted value for both the 'baseUnitValueFromValue:' and 'valueFromBaseUnitValue:' methods. You can create a unit converter for a base unit using the 'NSUnitConverterLinear' 'initWithCoefficient:' initializer, passing '1' as the coefficient. + * @details This class method returns an instance of the dimension class that represents the base unit of that dimension. e.g. NSUnitSpeed metersPerSecond = [NSUnitSpeed baseUnit]; * @return The converted Objective-C result. */ static Dimension base_unit(); /** * @brief Returns the `converter` property of `NSDimension`. - * @details The unit converter that describes how this unit converts to and from the base unit of its dimension. * @return The converted Objective-C result. */ UnitConverter converter() const; diff --git a/include/generated/directory_enumerator_base.h b/include/generated/directory_enumerator_base.h index 183b0b40..615c7e3d 100644 --- a/include/generated/directory_enumerator_base.h +++ b/include/generated/directory_enumerator_base.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSDirectoryEnumerator` (Foundation). - * @details An object that enumerates the contents of a directory. You obtain a directory enumerator using ''NSFileManager'''s 'enumeratorAtPath:' method. The enumeration provides the pathnames of all files and directories contained within that directory. These pathnames are relative to the directory. An enumeration is recursive, including the files of all subdirectories, and crosses device boundaries. An enumeration does not resolve symbolic links, or attempt to traverse symbolic links that point to directories. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref EnumeratorBase. * Use the typed template @ref DirectoryEnumerator to supply ObjectType. @@ -42,23 +41,21 @@ namespace cocoon explicit DirectoryEnumeratorBase(Adopt adopt); /** * @brief Calls `-[NSDirectoryEnumerator skipDescendants]`. - * @details Causes the receiver to skip recursion into the most recently obtained subdirectory. This method is identical to 'skipDescendents' except for the spelling. + * @details This method is spelled correctly. */ void skip_descendants() const; /** * @brief Calls `-[NSDirectoryEnumerator skipDescendents]`. - * @details Causes the receiver to skip recursion into the most recently obtained subdirectory. */ void skip_descendents() const; /** * @brief Returns the `directoryAttributes` property of `NSDirectoryEnumerator`. - * @details A dictionary with the attributes of the directory at which enumeration started. See the description of the 'fileAttributesAtPath:traverseLink:' method of ''NSFileManager'' for details on obtaining the attributes from the dictionary. * @return The converted Objective-C result. */ std::map directory_attributes() const; /** * @brief Returns the `fileAttributes` property of `NSDirectoryEnumerator`. - * @details A dictionary with the attributes of the most recently returned file or subdirectory (as referenced by the pathname). See the description of the 'fileAttributesAtPath:traverseLink:' method of ''NSFileManager'' for details on obtaining the attributes from the dictionary. + * @details For NSDirectoryEnumerators created with -enumeratorAtPath:, the -fileAttributes and -directoryAttributes methods return an NSDictionary containing the keys listed below. For NSDirectoryEnumerators created with -enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:, these two methods return nil. * @return The converted Objective-C result. */ std::map file_attributes() const; @@ -70,7 +67,7 @@ namespace cocoon bool is_enumerating_directory_post_order() const; /** * @brief Returns the `level` property of `NSDirectoryEnumerator`. - * @details The number of levels deep the current object is in the directory hierarchy being enumerated. The number of levels, with the directory passed to 'enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:' considered to be level '0'. + * @details This method returns the number of levels deep the current object is in the directory hierarchy being enumerated. The directory passed to -enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: is considered to be level 0. * @return The converted Objective-C result. */ std::uint64_t level() const; diff --git a/include/generated/distant_object_request.h b/include/generated/distant_object_request.h index f98c01fc..b67b9320 100644 --- a/include/generated/distant_object_request.h +++ b/include/generated/distant_object_request.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDistantObjectRequest` (Foundation). - * @details \@DeprecationSummary { Use ''NSXPCConnection'' instead. } An object used by the distributed objects system to help handle invocations between different processes. Do not create ''NSDistantObjectRequest'' objects directly. Unless you are getting involved with the low-level details of distributed objects, there should never be a need to access an ''NSDistantObjectRequest''. To intercept and possibly process requests yourself, implement the ''NSConnection'' delegate method ''NSConnectionDelegate/connection:handleRequest:''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -43,25 +42,21 @@ namespace cocoon explicit DistantObjectRequest(Adopt adopt); /** * @brief Calls `-[NSDistantObjectRequest replyWithException:]`. - * @details Sends a reply back to the sender of the request, signaling an exception if one is provided. * @param exception Argument converted to the Objective-C parameter of the same role. */ void reply_with_exception(const Exception& exception) const; /** * @brief Returns the `connection` property of `NSDistantObjectRequest`. - * @details The connection over which the request was received. * @return The converted Objective-C result. */ Connection connection() const; /** * @brief Returns the `conversation` property of `NSDistantObjectRequest`. - * @details The token object representing the conversation in which the request was received. * @return The converted Objective-C result. */ Object conversation() const; /** * @brief Returns the `invocation` property of `NSDistantObjectRequest`. - * @details The invocation object for the request. * @return The converted Objective-C result. */ Invocation invocation() const; diff --git a/include/generated/distributed_lock.h b/include/generated/distributed_lock.h index 12adb33f..a5ed7c1e 100644 --- a/include/generated/distributed_lock.h +++ b/include/generated/distributed_lock.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSDistributedLock` (Foundation). - * @details A lock that multiple applications on multiple hosts can use to restrict access to some shared resource, such as a file. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,30 +44,25 @@ namespace cocoon explicit DistributedLock(Adopt adopt); /** * @brief Calls `-[NSDistributedLock breakLock]`. - * @details Forces the lock to be relinquished. */ void break_lock() const; /** * @brief Calls `+[NSDistributedLock lockWithPath:]`. - * @details Returns an ''NSDistributedLock'' object initialized with the specified path. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static DistributedLock lock_with_path(const std::string& path); /** * @brief Calls `-[NSDistributedLock tryLock]`. - * @details Attempts to acquire the lock and immediately returns a Boolean value that indicates whether the attempt was successful. * @return The converted Objective-C result. */ bool try_lock() const; /** * @brief Calls `-[NSDistributedLock unlock]`. - * @details Relinquishes the receiver. */ void unlock() const; /** * @brief Returns the `lockDate` property of `NSDistributedLock`. - * @details The time the lock was acquired. * @return The converted Objective-C result. */ Date lock_date() const; diff --git a/include/generated/distributed_notification_center.h b/include/generated/distributed_notification_center.h index ebafd424..fe2370d2 100644 --- a/include/generated/distributed_notification_center.h +++ b/include/generated/distributed_notification_center.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSDistributedNotificationCenter` (Foundation). - * @details A notification dispatch mechanism that enables the broadcast of notifications across task boundaries. A ''DistributedNotificationCenter'' instance broadcasts ''NSNotification'' objects to objects in other tasks that have registered for the notification with their task's default distributed notification center. \#\#\# Principal Attributes - Notification dispatch table. See "Class at a Glance" > "Principal Attributes" in ''NotificationCenter'' for information about the dispatch table. In addition to the notification name and sender, dispatch table entries for distributed notification centers specify when the notification center delivers notifications to its observers. See the ''postNotificationName(:object:userInfo:deliverImmediately:)'' method, Suspending and Resuming Notification Delivery, and ''SuspensionBehavior'' for details. \#\#\# Commonly Used Methods - term ''default()'': Accesses the default distributed notification center. - term ''addObserver(:selector:name:object:suspensionBehavior:)'': Registers an object to receive a notification with a specified behavior when notification delivery is suspended. - term ''postNotificationName(:object:userInfo:deliverImmediately:)'': Creates and posts a notification. - term ''removeObserver(:name:object:)'': Specifies that an object no longer wants to receive certain notifications. \#\#\# Overview Each task has a default distributed notification center that you access with the ''default()'' class method. There may be different types of distributed notification centers. Currently there is a single type—'NSLocalNotificationCenterType'. This type of distributed notification center handles notifications that can be sent between tasks on a single computer. For communication between tasks on different computers, use [Distributed Objects Programming Topics](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DistrObjects/DistrObjects.html\#//apple_ref/doc/uid/10000102i). Posting a distributed notification is an expensive operation. The notification gets sent to a system-wide server that distributes it to all the tasks that have objects registered for distributed notifications. The latency between posting the notification and the notification's arrival in another task is unbounded. In fact, when too many notifications are posted and the server's queue fills up, notifications may be dropped. Distributed notifications are delivered via a task's run loop. A task must be running a run loop in one of the "common" modes, such as 'NSDefaultRunLoopMode', to receive a distributed notification. For multithreaded applications running in macOS 10.3 and later, distributed notifications are always delivered to the main thread. For multithreaded applications running in OS X v10.2.8 and earlier, notifications are delivered to the thread that first used the distributed notifications API, which in most cases is the main thread. > Important: > 'NSDistributedNotificationCenter' does not implement a secure communications protocol. When using distributed notifications, your app should treat any data passed in the notification as untrusted. See [Security Overview](https://developer.apple.com/library/archive/documentation/Security/Conceptual/Security_Overview/Introduction/Introduction.html\#//apple_ref/doc/uid/TP30000976) for general guidance on secure coding practices. > Note: > 'NSDistributedNotificationCenter' objects should not be used to send notifications between threads within the same task. Use [Distributed Objects Programming Topics](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DistrObjects/DistrObjects.html\#//apple_ref/doc/uid/10000102i) or the \ method \, instead. You can also setup an ''Port'' object to receive and distribute messages from other threads. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref NotificationCenter. * @@ -49,7 +48,6 @@ namespace cocoon using NotificationCenter::remove_observer; /** * @brief Calls `-[NSDistributedNotificationCenter addObserver:selector:name:object:]`. - * @details Adds an entry to the notification center's dispatch table with an observer, a selector, and an optional notification name and sender. This method calls ''addObserver(:selector:name:object:suspensionBehavior:)'' passing 'NSNotificationSuspensionBehaviorCoalesce' for 'suspensionBehavior'. - Parameters: - observer: An object registering as an observer. - aSelector: A selector that the notification center sends the observer to notify when posting the notification. - aName: The name of the notification for which to register the observer. When 'nil', the notification center doesn't use a notification's name to decide whether to deliver it to the observer. - anObject: The object whose notifications the observer wants to receive. When 'nil', the notification center doesn't use a notification's sender to decide whether to deliver it to the observer. * @param observer Argument converted to the Objective-C parameter of the same role. * @param a_selector Argument converted to the Objective-C parameter of the same role. * @param a_name Argument converted to the Objective-C parameter of the same role. @@ -58,7 +56,6 @@ namespace cocoon void add_observer(const Object& observer, const std::string& a_selector, const std::string& a_name, const std::string& an_object) const; /** * @brief Calls `-[NSDistributedNotificationCenter addObserver:selector:name:object:suspensionBehavior:]`. - * @details Adds an entry to the receiver's dispatch table with a specific observer and suspended-notifications behavior, and optional notification name and sender. The receiver does not retain 'observer'. Therefore, you should always send 'removeObserver:' or 'removeObserver:name:object:' to the receiver before releasing the observer. - Parameters: - observer: Object registering as an observer. Must not be 'nil'. - selector: Selector that specifies the message the receiver sends the observer to notify it of the notification posting. Must not be '0'. - name: The name of the notification for which to register the observer; that is, only notifications with this name are delivered to the observer. When 'nil', the notification center doesn't use a notification's name to decide whether to deliver it to the observer. - object: The object whose notifications the observer wants to receive; that is, only notifications sent by this sender are delivered to the observer. When 'nil', the notification center doesn't use a notification's sender to decide whether to deliver it to the observer. - suspensionBehavior: Notification posting behavior when notification delivery is suspended. * @param observer Argument converted to the Objective-C parameter of the same role. * @param selector Argument converted to the Objective-C parameter of the same role. * @param name Argument converted to the Objective-C parameter of the same role. @@ -68,27 +65,23 @@ namespace cocoon void add_observer(const Object& observer, const std::string& selector, const std::string& name, const std::string& object, NotificationSuspensionBehavior suspension_behavior) const; /** * @brief Calls `+[NSDistributedNotificationCenter defaultCenter]`. - * @details Returns the default distributed notification center, representing the local notification center for the computer. This method calls ''DistributedNotificationCenter/forType(:)'' with an argument of 'NSLocalNotificationCenterType'. - Returns: Default distributed notification center for the computer. * @return The converted Objective-C result. */ static DistributedNotificationCenter default_center(); /** * @brief Calls `+[NSDistributedNotificationCenter notificationCenterForType:]`. - * @details Returns the distributed notification center for a particular notification center type. Currently only one type, 'NSLocalNotificationCenterType', is supported. - Parameter notificationCenterType: Notification center type being inquired about. - Returns: Distributed notification center for 'notificationCenterType'. * @param notification_center_type Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static DistributedNotificationCenter notification_center_for_type(const std::string& notification_center_type); /** * @brief Calls `-[NSDistributedNotificationCenter postNotificationName:object:]`. - * @details Creates a notification, and posts it to the receiver. This method invokes ''postNotificationName(:object:userInfo:deliverImmediately:)'' with 'userInfo:nil deliverImmediately:NO'. - Parameters: - aName: Name of the notification to post. Must not be 'nil'. - anObject: Sender of the notification. May be 'nil'. * @param a_name Argument converted to the Objective-C parameter of the same role. * @param an_object Argument converted to the Objective-C parameter of the same role. */ void post_notification_name(const std::string& a_name, const std::string& an_object) const; /** * @brief Calls `-[NSDistributedNotificationCenter postNotificationName:object:userInfo:]`. - * @details Creates a notification with information, and posts it to the receiver. This method invokes ''postNotificationName(:object:userInfo:deliverImmediately:)'' with 'deliverImmediately:NO'. - Parameters: - aName: Name of the notification to post. Must not be 'nil'. - anObject: Sender of the notification. May be 'nil'. - aUserInfo: Dictionary containing additional information. May be 'nil'. * @param a_name Argument converted to the Objective-C parameter of the same role. * @param an_object Argument converted to the Objective-C parameter of the same role. * @param a_user_info Argument converted to the Objective-C parameter of the same role. @@ -96,7 +89,6 @@ namespace cocoon void post_notification_name(const std::string& a_name, const std::string& an_object, const std::vector>& a_user_info) const; /** * @brief Calls `-[NSDistributedNotificationCenter postNotificationName:object:userInfo:deliverImmediately:]`. - * @details Creates a notification with information and an immediate-delivery specifier, and posts it to the receiver. This is the preferred method for posting notifications. The 'userInfo' dictionary is serialized as a property list, so it can be passed to another task. In the receiving task, it is deserialized back into a dictionary. - Parameters: - name: Name of the notification to post. Must not be 'nil'. - object: Sender of the notification. May be 'nil'. - userInfo: Dictionary containing additional information. May be 'nil'. - deliverImmediately: When 'NO', the receiver delivers notifications to their observers according to the suspended-notification behavior specified in the corresponding dispatch table entry. When 'YES', the receiver delivers the notification immediately to its observers. * @param name Argument converted to the Objective-C parameter of the same role. * @param object Argument converted to the Objective-C parameter of the same role. * @param user_info Argument converted to the Objective-C parameter of the same role. @@ -105,7 +97,6 @@ namespace cocoon void post_notification_name(const std::string& name, const std::string& object, const std::vector>& user_info, bool deliver_immediately) const; /** * @brief Calls `-[NSDistributedNotificationCenter postNotificationName:object:userInfo:options:]`. - * @details Creates a notification with information, and posts it to the receiver. The 'userInfo' dictionary is serialized as a property list, so it can be passed to another task. In the receiving task, it is deserialized back into a dictionary. - Parameters: - name: Name of the notification to post. Must not be 'nil'. - object: Sender of the notification. May be 'nil'. - userInfo: Dictionary containing additional information. May be 'nil'. - options: Specifies how the notification is posted to the task and when to deliver it to its observers. * @param name Argument converted to the Objective-C parameter of the same role. * @param object Argument converted to the Objective-C parameter of the same role. * @param user_info Argument converted to the Objective-C parameter of the same role. @@ -114,7 +105,6 @@ namespace cocoon void post_notification_name(const std::string& name, const std::string& object, const std::vector>& user_info, DistributedNotificationOptions options) const; /** * @brief Calls `-[NSDistributedNotificationCenter removeObserver:name:object:]`. - * @details Removes matching entries from the receiver's dispatch table. Be sure to invoke this method before deallocating the observer object. - Parameters: - observer: Observer to remove from the dispatch table. Specify an observer to remove only entries for this observer. When 'nil', the receiver does not use notification observers as criteria for removal. - aName: Name of the notification to remove from dispatch table. Specify a notification name to remove only entries that specify this notification name. When 'nil', the receiver does not use notification names as criteria for removal. - anObject: Sender to remove from the dispatch table. Specify a notification sender to remove only entries that specify this sender. When 'nil', the receiver does not use notification senders as criteria for removal. * @param observer Argument converted to the Objective-C parameter of the same role. * @param a_name Argument converted to the Objective-C parameter of the same role. * @param an_object Argument converted to the Objective-C parameter of the same role. @@ -122,13 +112,11 @@ namespace cocoon void remove_observer(const Object& observer, const std::string& a_name, const std::string& an_object) const; /** * @brief Returns the `suspended` property of `NSDistributedNotificationCenter`. - * @details Suspends or resumes notification delivery. Setting this to 'true' suspends notification delivery, enabling the variety of suspension behaviors enumerated in ''DistributedNotificationCenter/SuspensionBehavior''. Setting this to 'false' resumes immediate delivery of notifications. 'NSApplication' automatically suspends distributed notification delivery when the application is not active. Applications based on the Application Kit framework should let AppKit manage the suspension of notification delivery. Foundation-only programs may have occasional need to use this property. * @return The converted Objective-C result. */ bool suspended() const; /** * @brief Sets the `suspended` property of `NSDistributedNotificationCenter`. - * @details Suspends or resumes notification delivery. Setting this to 'true' suspends notification delivery, enabling the variety of suspension behaviors enumerated in ''DistributedNotificationCenter/SuspensionBehavior''. Setting this to 'false' resumes immediate delivery of notifications. 'NSApplication' automatically suspends distributed notification delivery when the application is not active. Applications based on the Application Kit framework should let AppKit manage the suspension of notification delivery. Foundation-only programs may have occasional need to use this property. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_suspended(bool value) const; diff --git a/include/generated/energy_formatter.h b/include/generated/energy_formatter.h index 3c623099..7a6caf2c 100644 --- a/include/generated/energy_formatter.h +++ b/include/generated/energy_formatter.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSEnergyFormatter` (Foundation). - * @details A formatter that provides localized descriptions of energy values. > Note: > As of iOS 10, macOS 10.12, tvOS 10, and watchOS 3, Foundation provides the ''MeasurementFormatter'' class, which can be used to represent quantities of ''UnitEnergy'' to provide equivalent functionality to ''EnergyFormatter''. You are encouraged to transition to these new Foundation Units and Measurements APIs whenever possible. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -51,14 +50,12 @@ namespace cocoon explicit EnergyFormatter(Adopt adopt); /** * @brief Calls `-[NSEnergyFormatter stringFromJoules:]`. - * @details Returns an energy string for the provided value in joules. Formats a number in joules to a localized string with the locale-appropriate unit and an appropriate scale (e.g. 10.3J = 2.46cal in the US locale). * @param number_in_joules Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_joules(double number_in_joules) const; /** * @brief Calls `-[NSEnergyFormatter stringFromValue:unit:]`. - * @details Returns an energy string for the provided value and unit. * @param value Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -66,7 +63,6 @@ namespace cocoon std::string string_from_value(double value, EnergyFormatterUnit unit) const; /** * @brief Calls `-[NSEnergyFormatter unitStringFromJoules:usedUnit:]`. - * @details Returns a unit string based on the provided value in joules. Returns the locale-appropriate unit, the same unit used by 'stringFromJoules:'. * @param number_in_joules Argument converted to the Objective-C parameter of the same role. * @param unitp Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -74,7 +70,6 @@ namespace cocoon std::string unit_string_from_joules(double number_in_joules, EnergyFormatterUnit* unitp) const; /** * @brief Calls `-[NSEnergyFormatter unitStringFromValue:unit:]`. - * @details Returns a unit string for the provided value and unit. Returns a localized string of the given unit, and if the unit is singular or plural is based on the given number. * @param value Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -82,37 +77,31 @@ namespace cocoon std::string unit_string_from_value(double value, EnergyFormatterUnit unit) const; /** * @brief Returns the `forFoodEnergyUse` property of `NSEnergyFormatter`. - * @details A Boolean value that indicates whether the resulting string is used to represent food energy. The default value is 'NO'. If set to 'YES', 'NSEnergyFormatterUnitKilocalorie' may be displayed as "C" instead of "kcal". * @return The converted Objective-C result. */ bool is_for_food_energy_use() const; /** * @brief Sets the `forFoodEnergyUse` property of `NSEnergyFormatter`. - * @details A Boolean value that indicates whether the resulting string is used to represent food energy. The default value is 'NO'. If set to 'YES', 'NSEnergyFormatterUnitKilocalorie' may be displayed as "C" instead of "kcal". * @param value Argument converted to the Objective-C parameter of the same role. */ void set_for_food_energy_use(bool value) const; /** * @brief Returns the `numberFormatter` property of `NSEnergyFormatter`. - * @details The number formatter used to format the numbers in an energy string. The default value is an 'NSNumberFormatter' with 'NSNumberFormatterDecimalStyle'. * @return The converted Objective-C result. */ NumberFormatter number_formatter() const; /** * @brief Sets the `numberFormatter` property of `NSEnergyFormatter`. - * @details The number formatter used to format the numbers in an energy string. The default value is an 'NSNumberFormatter' with 'NSNumberFormatterDecimalStyle'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_number_formatter(const NumberFormatter& value) const; /** * @brief Returns the `unitStyle` property of `NSEnergyFormatter`. - * @details The unit style used when creating string representations of energy values. The default value is 'NSFormattingUnitStyleMedium'. * @return The converted Objective-C result. */ FormattingUnitStyle unit_style() const; /** * @brief Sets the `unitStyle` property of `NSEnergyFormatter`. - * @details The unit style used when creating string representations of energy values. The default value is 'NSFormattingUnitStyleMedium'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_unit_style(FormattingUnitStyle value) const; diff --git a/include/generated/enumerator_base.h b/include/generated/enumerator_base.h index 7abd880f..26e78fe4 100644 --- a/include/generated/enumerator_base.h +++ b/include/generated/enumerator_base.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSEnumerator` (Foundation). - * @details An abstract class whose subclasses enumerate collections of objects, such as arrays and dictionaries. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref Enumerator to supply ObjectType. * @@ -40,13 +39,11 @@ namespace cocoon explicit EnumeratorBase(Adopt adopt); /** * @brief Calls `-[NSEnumerator nextObject]`. - * @details Returns the next object from the collection being enumerated. * @return The converted Objective-C result. */ Object next_object() const; /** * @brief Returns the `allObjects` property of `NSEnumerator`. - * @details The array of unenumerated objects. * @return The converted Objective-C result. */ std::vector all_objects() const; diff --git a/include/generated/enums.h b/include/generated/enums.h index dc96fff4..c3187b37 100644 --- a/include/generated/enums.h +++ b/include/generated/enums.h @@ -86,15 +86,6 @@ namespace cocoon Left = 8, }; - /** @brief Wraps the Objective-C enumeration `CGRectEdge`. */ - enum class CGRectEdge : std::uint32_t - { - MinXEdge = 0, - MinYEdge = 1, - MaxXEdge = 2, - MaxYEdge = 3, - }; - /** @brief Wraps the Objective-C option set `NSActivityOptions`. Combine option sets with `|` and test them with `test_flag`. */ enum class ActivityOptions : std::uint64_t { @@ -290,7 +281,6 @@ namespace cocoon FullScreen = 1024, AutoHideToolbar = 2048, DisableCursorLocationAssistance = 4096, - DisableScreenCornerInteractions = 32768, }; constexpr ApplicationPresentationOptions operator|(ApplicationPresentationOptions a, ApplicationPresentationOptions b) @@ -1084,40 +1074,6 @@ namespace cocoon return (static_cast(value) & static_cast(flag)) != 0; } - /** @brief Wraps the Objective-C option set `NSControlEvents`. Combine option sets with `|` and test them with `test_flag`. */ - enum class ControlEvents : std::uint64_t - { - TrackingBegan = 1, - TrackingRepeated = 2, - TrackingInside = 4, - TrackingOutside = 8, - TrackingEntered = 16, - TrackingExited = 32, - TrackingEndedInside = 64, - TrackingEndedOutside = 128, - TrackingCancelled = 256, - ValueChanged = 4096, - PrimaryActionTriggered = 8192, - MenuActionTriggered = 16384, - AllTrackingEvents = 4095, - ApplicationReserved = 251658240, - SystemReserved = 4026531840, - AllEvents = 4294967295, - }; - - constexpr ControlEvents operator|(ControlEvents a, ControlEvents b) - { - return static_cast(static_cast(a) | static_cast(b)); - } - constexpr ControlEvents operator&(ControlEvents a, ControlEvents b) - { - return static_cast(static_cast(a) & static_cast(b)); - } - constexpr bool test_flag(ControlEvents value, ControlEvents flag) - { - return (static_cast(value) & static_cast(flag)) != 0; - } - /** @brief Wraps the Objective-C enumeration `NSControlSize`. */ enum class ControlSize : std::uint64_t { @@ -2852,14 +2808,6 @@ namespace cocoon Alerts = 3, }; - /** @brief Wraps the Objective-C enumeration `NSMenuItemImageVisibility`. */ - enum class MenuItemImageVisibility : std::int64_t - { - Automatic = 0, - Visible = 1, - Hidden = 2, - }; - /** @brief Wraps the Objective-C enumeration `NSMenuPresentationStyle`. */ enum class MenuPresentationStyle : std::int64_t { @@ -3527,26 +3475,6 @@ namespace cocoon Ask = 2, }; - /** @brief Wraps the Objective-C option set `NSScreenTouchCapabilities`. Combine option sets with `|` and test them with `test_flag`. */ - enum class ScreenTouchCapabilities : std::uint64_t - { - None = 0, - MultiTouch = 1, - }; - - constexpr ScreenTouchCapabilities operator|(ScreenTouchCapabilities a, ScreenTouchCapabilities b) - { - return static_cast(static_cast(a) | static_cast(b)); - } - constexpr ScreenTouchCapabilities operator&(ScreenTouchCapabilities a, ScreenTouchCapabilities b) - { - return static_cast(static_cast(a) & static_cast(b)); - } - constexpr bool test_flag(ScreenTouchCapabilities value, ScreenTouchCapabilities flag) - { - return (static_cast(value) & static_cast(flag)) != 0; - } - /** @brief Wraps the Objective-C enumeration `NSScrollElasticity`. */ enum class ScrollElasticity : std::int64_t { @@ -3692,14 +3620,6 @@ namespace cocoon MomentaryAccelerator = 3, }; - /** @brief Wraps the Objective-C enumeration `NSSegmentedControlRole`. */ - enum class SegmentedControlRole : std::int64_t - { - Automatic = 0, - Tabs = 1, - ValueSelection = 2, - }; - /** @brief Wraps the Objective-C enumeration `NSSelectionAffinity`. */ enum class SelectionAffinity : std::uint64_t { @@ -3882,34 +3802,6 @@ namespace cocoon return (static_cast(value) & static_cast(flag)) != 0; } - /** @brief Wraps the Objective-C option set `NSStringEnumerationOptions`. Combine option sets with `|` and test them with `test_flag`. */ - enum class StringEnumerationOptions : std::uint64_t - { - ByLines = 0, - ByParagraphs = 1, - ByComposedCharacterSequences = 2, - ByWords = 3, - BySentences = 4, - ByCaretPositions = 5, - ByDeletionClusters = 6, - Reverse = 256, - SubstringNotRequired = 512, - Localized = 1024, - }; - - constexpr StringEnumerationOptions operator|(StringEnumerationOptions a, StringEnumerationOptions b) - { - return static_cast(static_cast(a) | static_cast(b)); - } - constexpr StringEnumerationOptions operator&(StringEnumerationOptions a, StringEnumerationOptions b) - { - return static_cast(static_cast(a) & static_cast(b)); - } - constexpr bool test_flag(StringEnumerationOptions value, StringEnumerationOptions flag) - { - return (static_cast(value) & static_cast(flag)) != 0; - } - /** @brief Wraps the Objective-C enumeration `NSTIFFCompression`. */ enum class TIFFCompression : std::uint64_t { @@ -4137,28 +4029,8 @@ namespace cocoon Natural = 4, }; - /** @brief Wraps the Objective-C option set `NSTextAttachmentViewProviderReusePolicy`. Combine option sets with `|` and test them with `test_flag`. */ - enum class TextAttachmentViewProviderReusePolicy : std::uint64_t - { - OnScrollingOutOfViewport = 1, - OnEditingInlineParagraphs = 2, - }; - - constexpr TextAttachmentViewProviderReusePolicy operator|(TextAttachmentViewProviderReusePolicy a, TextAttachmentViewProviderReusePolicy b) - { - return static_cast(static_cast(a) | static_cast(b)); - } - constexpr TextAttachmentViewProviderReusePolicy operator&(TextAttachmentViewProviderReusePolicy a, TextAttachmentViewProviderReusePolicy b) - { - return static_cast(static_cast(a) & static_cast(b)); - } - constexpr bool test_flag(TextAttachmentViewProviderReusePolicy value, TextAttachmentViewProviderReusePolicy flag) - { - return (static_cast(value) & static_cast(flag)) != 0; - } - /** @brief Wraps the Objective-C enumeration `NSTextBlockDimension`. */ - enum class TextBlockDimension : std::int64_t + enum class TextBlockDimension : std::uint64_t { Width = 0, MinimumWidth = 1, @@ -4166,12 +4038,6 @@ namespace cocoon Height = 4, MinimumHeight = 5, MaximumHeight = 6, - TextBlockWidth = 0, - TextBlockMinimumWidth = 1, - TextBlockMaximumWidth = 2, - TextBlockHeight = 4, - TextBlockMinimumHeight = 5, - TextBlockMaximumHeight = 6, }; /** @brief Wraps the Objective-C enumeration `NSTextBlockLayer`. */ @@ -4180,31 +4046,22 @@ namespace cocoon Padding = -1, Border = 0, Margin = 1, - TextBlockPadding = -1, - TextBlockBorder = 0, - TextBlockMargin = 1, }; /** @brief Wraps the Objective-C enumeration `NSTextBlockValueType`. */ - enum class TextBlockValueType : std::int64_t + enum class TextBlockValueType : std::uint64_t { - Absolute = 0, - Percentage = 1, - TextBlockAbsoluteValueType = 0, - TextBlockPercentageValueType = 1, + AbsoluteValueType = 0, + PercentageValueType = 1, }; /** @brief Wraps the Objective-C enumeration `NSTextBlockVerticalAlignment`. */ - enum class TextBlockVerticalAlignment : std::int64_t + enum class TextBlockVerticalAlignment : std::uint64_t { - Top = 0, - Middle = 1, - Bottom = 2, - Baseline = 3, - TextBlockTopAlignment = 0, - TextBlockMiddleAlignment = 1, - TextBlockBottomAlignment = 2, - TextBlockBaselineAlignment = 3, + TopAlignment = 0, + MiddleAlignment = 1, + BottomAlignment = 2, + BaselineAlignment = 3, }; /** @brief Wraps the Objective-C option set `NSTextCheckingType`. Combine option sets with `|` and test them with `test_flag`. */ @@ -4426,14 +4283,6 @@ namespace cocoon Sentence = 4, }; - /** @brief Wraps the Objective-C enumeration `NSTextSelectionMode`. */ - enum class TextSelectionMode : std::int64_t - { - Editable = 0, - Selectable = 1, - NonInteractive = 2, - }; - /** @brief Wraps the Objective-C enumeration `NSTextSelectionNavigationDestination`. */ enum class TextSelectionNavigationDestination : std::int64_t { @@ -4457,13 +4306,6 @@ namespace cocoon Down = 5, }; - /** @brief Wraps the Objective-C enumeration `NSTextSelectionNavigationLayoutOrientation`. */ - enum class TextSelectionNavigationLayoutOrientation : std::int64_t - { - Horizontal = 0, - Vertical = 1, - }; - /** @brief Wraps the Objective-C option set `NSTextSelectionNavigationModifier`. Combine option sets with `|` and test them with `test_flag`. */ enum class TextSelectionNavigationModifier : std::uint64_t { @@ -4522,12 +4364,10 @@ namespace cocoon }; /** @brief Wraps the Objective-C enumeration `NSTextTableLayoutAlgorithm`. */ - enum class TextTableLayoutAlgorithm : std::int64_t + enum class TextTableLayoutAlgorithm : std::uint64_t { - Automatic = 0, - Fixed = 1, - TextTableAutomaticLayoutAlgorithm = 0, - TextTableFixedLayoutAlgorithm = 1, + AutomaticLayoutAlgorithm = 0, + FixedLayoutAlgorithm = 1, }; /** @brief Wraps the Objective-C enumeration `NSTickMarkPosition`. */ @@ -4607,14 +4447,6 @@ namespace cocoon Collapsed = 2, }; - /** @brief Wraps the Objective-C enumeration `NSToolbarItemGroupRole`. */ - enum class ToolbarItemGroupRole : std::int64_t - { - Automatic = 0, - Tabs = 1, - ValueSelection = 2, - }; - /** @brief Wraps the Objective-C enumeration `NSToolbarItemGroupSelectionMode`. */ enum class ToolbarItemGroupSelectionMode : std::int64_t { @@ -5035,14 +4867,6 @@ namespace cocoon return (static_cast(value) & static_cast(flag)) != 0; } - /** @brief Wraps the Objective-C enumeration `NSViewExclusiveGestureBehavior`. */ - enum class ViewExclusiveGestureBehavior : std::int64_t - { - Inherit = 0, - Exclusive = 1, - NotExclusive = 2, - }; - /** @brief Wraps the Objective-C enumeration `NSViewLayerContentsPlacement`. */ enum class ViewLayerContentsPlacement : std::int64_t { @@ -5408,17 +5232,6 @@ namespace cocoon InteractiveStreaming = 3, }; - /** @brief Wraps the Objective-C enumeration `NSWritingToolsCoordinatorTextAnimation`. */ - enum class WritingToolsCoordinatorTextAnimation : std::int64_t - { - Anticipate = 0, - Remove = 1, - Insert = 2, - AnticipateInactive = 8, - Translate = 9, - IndicateGrammar = 10, - }; - /** @brief Wraps the Objective-C enumeration `NSWritingToolsCoordinatorTextUpdateReason`. */ enum class WritingToolsCoordinatorTextUpdateReason : std::int64_t { diff --git a/include/generated/error.h b/include/generated/error.h index a7d55efd..dbde7a7e 100644 --- a/include/generated/error.h +++ b/include/generated/error.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSError` (Foundation). - * @details Information about an error condition including a domain, a domain-specific error code, and application-specific information. Objective-C methods can signal an error condition by returning an ''NSError'' object by reference, which provides additional information about the kind of error and any underlying cause, if one can be determined. An ''NSError'' object may also provide localized error descriptions suitable for display to the user in its user info dictionary. See [Error Handling Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ErrorHandlingCocoa/ErrorHandling/ErrorHandling.html\#//apple_ref/doc/uid/TP40001806) for more information. Methods in Foundation and other Cocoa frameworks most often produce errors in the Cocoa error domain (''NSCocoaErrorDomain''); error codes for the Cocoa Error Domain are documented in the \. There are also predefined domains corresponding to Mach (''NSMachErrorDomain''), POSIX (''NSPOSIXErrorDomain''), and Carbon (''NSOSStatusErrorDomain'') errors. ''NSError'' is "toll-free bridged" with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information. \#\#\# Subclassing Notes Applications may choose to create subclasses of 'NSError', for example, to provide better localized error strings by overriding ''localizedDescription''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -34,63 +33,61 @@ namespace cocoon explicit Error(Adopt adopt); /** * @brief Calls `+[NSError setUserInfoValueProviderForDomain:provider:]`. - * @details Specifies a block to call when the corresponding property is not present in the user info dictionary. The provider is called synchronously from the implementations of \@c localizedDescription, \@c localizedFailureReason, \@c localizedRecoverySuggestion, \@c localizedRecoveryOptions, \@c recoveryAttempter, \@c helpAnchor, and \@c debugDescription when the underlying value is not present in the \@c userInfo dictionary of NSError instances with the specified domain. The provider should return \@c nil for any keys it is not able to provide and any keys it does not recognize. The results are not cached. It is expected that only the “owner” of an NSError domain specifies the provider, and this is done once. This facility is not meant for consumers of errors to customize the userInfo entries. This facility should not be used to customize the behaviors of error domains provided by the system. If an appropriate result for the requested key cannot be provided, return nil rather than choosing to manufacture a generic fallback response such as "Operation could not be completed, error 42." 'NSError' will take care of the fallback cases. \@param errorDomain The error domain of the provider. \@param provider A block to be executed synchronously at the time a corresponding property is accessed. + * @details Specify a block which will be called from the implementations of localizedDescription, localizedFailureReason, localizedRecoverySuggestion, localizedRecoveryOptions, recoveryAttempter, helpAnchor, and debugDescription when the underlying value for these is not present in the userInfo dictionary of NSError instances with the specified domain. The provider will be called with the userInfo key corresponding to the queried property: For instance, NSLocalizedDescriptionKey for localizedDescription. The provider should return nil for any keys it is not able to provide and, very importantly, any keys it does not recognize (since we may extend the list of keys in future releases). The specified block will be called synchronously at the time when the above properties are queried. The results are not cached. This provider is optional. It enables localization and formatting of error messages to be done lazily; rather than populating the userInfo at NSError creation time, these keys will be fetched on-demand when asked for. It is expected that only the “owner” of an NSError domain specifies the provider for the domain, and this is done once. This facility is not meant for consumers of errors to customize the userInfo entries. This facility should not be used to customize the behaviors of error domains provided by the system. If an appropriate result for the requested key cannot be provided, return nil rather than choosing to manufacture a generic fallback response such as "Operation could not be completed, error 42." NSError will take care of the fallback cases. * @param error_domain Argument converted to the Objective-C parameter of the same role. * @param provider Argument converted to the Objective-C parameter of the same role. */ static void set_user_info_value_provider_for_domain(const std::string& error_domain, std::function provider); /** * @brief Calls `+[NSError userInfoValueProviderForDomain:]`. - * @details Returns any user info provider specified for a given error domain. \@param errorDomain The error domain of the user info provider. \@return The user info provider of the error domain, or \@c nil if none is specified. * @param error_domain Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::function user_info_value_provider_for_domain(const std::string& error_domain); /** * @brief Returns the `code` property of `NSError`. - * @details The error code. Codes are domain-specific. * @return The converted Objective-C result. */ std::int64_t code() const; /** * @brief Returns the `domain` property of `NSError`. - * @details A string containing the error domain. Domains are described by names that are arbitrary strings used to differentiate groups of codes; for custom domains, using reverse-DNS naming will help avoid conflicts. + * @details These define the error. Domains are described by names that are arbitrary strings used to differentiate groups of codes; for custom domain using reverse-DNS naming will help avoid conflicts. Codes are domain-specific. * @return The converted Objective-C result. */ std::string domain() const; /** * @brief Returns the `helpAnchor` property of `NSError`. - * @details A string to display in response to an alert panel help anchor button being pressed. The object in the user info dictionary for the key \@c NSHelpAnchorErrorKey. Returns \@c nil if not present. + * @details Return the help anchor that can be used to create a help button to accompany the error when it's displayed to the user. This is done automatically by +[NSAlert alertWithError:], which the presentError: variants in NSApplication go through. The default implementation of this picks up the value of the NSHelpAnchorErrorKey from the userInfo dictionary. If not present, it consults the userInfoValueProvider for the domain. If that returns nil, this also returns nil. * @return The converted Objective-C result. */ std::string help_anchor() const; /** * @brief Returns the `localizedDescription` property of `NSError`. - * @details A string containing the localized description of the error. For instance, for 'NSFileReadNoPermissionError': "The file "File Name" couldn't be opened because you don't have permission to view it.". This message should ideally indicate what failed and why it failed. This value either comes from 'NSLocalizedDescriptionKey', or 'NSLocalizedFailureErrorKey' + 'NSLocalizedFailureReasonErrorKey', or 'NSLocalizedFailureErrorKey'. The steps this takes to construct the description include: 1. Look for NSLocalizedDescriptionKey in userInfo, use value as-is if present. 2. Look for NSLocalizedFailureErrorKey in userInfo. If present, use, combining with value for NSLocalizedFailureReasonErrorKey if available. 3. Fetch NSLocalizedDescriptionKey from userInfoValueProvider, use value as-is if present. 4. Fetch NSLocalizedFailureErrorKey from userInfoValueProvider. If present, use, combining with value for NSLocalizedFailureReasonErrorKey if available. 5. Look for NSLocalizedFailureReasonErrorKey in userInfo or from userInfoValueProvider; combine with generic "Operation failed" message. 6. Last resort localized but barely-presentable string manufactured from domain and code. The result is never nil. This value either comes from \@c NSLocalizedDescriptionKey, or \@c NSLocalizedFailureErrorKey combined with \@c NSLocalizedFailureReasonErrorKey, or a last-resort string manufactured from the domain and code. + * @details The primary user-presentable message for the error, for instance for NSFileReadNoPermissionError: "The file "File Name" couldn't be opened because you don't have permission to view it.". This message should ideally indicate what failed and why it failed. This value either comes from NSLocalizedDescriptionKey, or NSLocalizedFailureErrorKey+NSLocalizedFailureReasonErrorKey, or NSLocalizedFailureErrorKey. The steps this takes to construct the description include: 1. Look for NSLocalizedDescriptionKey in userInfo, use value as-is if present. 2. Look for NSLocalizedFailureErrorKey in userInfo. If present, use, combining with value for NSLocalizedFailureReasonErrorKey if available. 3. Fetch NSLocalizedDescriptionKey from userInfoValueProvider, use value as-is if present. 4. Fetch NSLocalizedFailureErrorKey from userInfoValueProvider. If present, use, combining with value for NSLocalizedFailureReasonErrorKey if available. 5. Look for NSLocalizedFailureReasonErrorKey in userInfo or from userInfoValueProvider; combine with generic "Operation failed" message. 6. Last resort localized but barely-presentable string manufactured from domain and code. The result is never nil. * @return The converted Objective-C result. */ std::string localized_description() const; /** * @brief Returns the `localizedFailureReason` property of `NSError`. - * @details A string containing the localized explanation of the reason for the error. Return a complete sentence which describes why the operation failed. For instance, for 'NSFileReadNoPermissionError': "You don't have permission.". In many cases this will be just the "because" part of the error message (but as a complete sentence, which makes localization easier). Default implementation of this picks up the value of 'NSLocalizedFailureReasonErrorKey' from the userInfo dictionary. If not present, it consults the 'userInfoValueProvider' for the domain, and if that returns 'nil', this also returns 'nil'. The object in the user info dictionary for the key \@c NSLocalizedFailureReasonErrorKey. If not present, consults the \@c userInfoValueProvider for the domain. Returns \@c nil if unavailable. + * @details Return a complete sentence which describes why the operation failed. For instance, for NSFileReadNoPermissionError: "You don't have permission.". In many cases this will be just the "because" part of the error message (but as a complete sentence, which makes localization easier). Default implementation of this picks up the value of NSLocalizedFailureReasonErrorKey from the userInfo dictionary. If not present, it consults the userInfoValueProvider for the domain, and if that returns nil, this also returns nil. * @return The converted Objective-C result. */ std::string localized_failure_reason() const; /** * @brief Returns the `localizedRecoveryOptions` property of `NSError`. - * @details An array containing the localized titles of buttons appropriate for displaying in an alert panel. The object in the user info dictionary for the key \@c NSLocalizedRecoveryOptionsErrorKey. These should match the string provided as a part of 'localizedRecoverySuggestion'. The first string would be the title of the right-most and default button, the second one next to it, and so on. If used in an alert the corresponding default return values are 'NSAlertFirstButtonReturn' + 'n'. Default implementation of this picks up the value of 'NSLocalizedRecoveryOptionsErrorKey' from the 'userInfo' dictionary. If not present, it consults the 'userInfoValueProvider' for the domain, and if that returns 'nil', this also returns 'nil'. 'nil' return usually implies no special suggestion, which would imply a single "OK" button. Returns \@c nil if no recovery options are available, which typically implies a single "OK" button. + * @details Return titles of buttons that are appropriate for displaying in an alert. These should match the string provided as a part of localizedRecoverySuggestion. The first string would be the title of the right-most and default button, the second one next to it, and so on. If used in an alert the corresponding default return values are NSAlertFirstButtonReturn + n. Default implementation of this picks up the value of NSLocalizedRecoveryOptionsErrorKey from the userInfo dictionary. If not present, it consults the userInfoValueProvider for the domain, and if that returns nil, this also returns nil. nil return usually implies no special suggestion, which would imply a single "OK" button. * @return The converted Objective-C result. */ std::vector localized_recovery_options() const; /** * @brief Returns the `localizedRecoverySuggestion` property of `NSError`. - * @details A string containing the localized recovery suggestion for the error. For instance, for 'NSFileReadNoPermissionError': "To view or change permissions, select the item in the Finder and choose File > Get Info.". The default implementation of this picks up the value of 'NSLocalizedRecoverySuggestionErrorKey' from the 'userInfo' dictionary. If not present, it consults the 'userInfoValueProvider' for the domain, and if that returns 'nil', this also returns 'nil'. The object in the user info dictionary for the key \@c NSLocalizedRecoverySuggestionErrorKey. The returned string is suitable for displaying as the secondary message in an alert panel. Returns \@c nil if unavailable. + * @details Return the string that can be displayed as the "informative" (aka "secondary") message on an alert panel. For instance, for NSFileReadNoPermissionError: "To view or change permissions, select the item in the Finder and choose File > Get Info.". Default implementation of this picks up the value of NSLocalizedRecoverySuggestionErrorKey from the userInfo dictionary. If not present, it consults the userInfoValueProvider for the domain, and if that returns nil, this also returns nil. * @return The converted Objective-C result. */ std::string localized_recovery_suggestion() const; /** * @brief Returns the `recoveryAttempter` property of `NSError`. - * @details The object in the user info dictionary corresponding to the \@c NSRecoveryAttempterErrorKey key. The recovery attempter must be an object that conforms to the \@c NSErrorRecoveryAttempting informal protocol. It must be able to correctly interpret an index into the \@c localizedRecoveryOptions array. The default implementation of this picks up the value of 'NSRecoveryAttempterErrorKey' from the 'userInfo' dictionary. If not present, it consults the 'userInfoValueProvider' for the domain. If that returns 'nil', this also returns 'nil'. Returns \@c nil if not present in the user info or from the \@c userInfoValueProvider. + * @details Return an object that conforms to the NSErrorRecoveryAttempting informal protocol. The recovery attempter must be an object that can correctly interpret an index into the array returned by localizedRecoveryOptions. The default implementation of this picks up the value of NSRecoveryAttempterErrorKey from the userInfo dictionary. If not present, it consults the userInfoValueProvider for the domain. If that returns nil, this also returns nil. * @return The converted Objective-C result. */ Object recovery_attempter() const; @@ -102,7 +99,7 @@ namespace cocoon std::vector underlying_errors() const; /** * @brief Returns the `userInfo` property of `NSError`. - * @details The user info dictionary. Contains application-specific data related to the error. Examples of keys that might be included are \@c NSLocalizedDescriptionKey, \@c NSFilePathErrorKey, and \@c NSUnderlyingErrorKey. + * @details Additional info which may be used to describe the error further. Examples of keys that might be included in here are "Line Number", "Failed URL", etc. Embedding other errors in here can also be used as a way to communicate underlying reasons for failures; for instance "File System Error" embedded in the userInfo of an NSError returned from a higher level document object. If the embedded error information is itself NSError, the standard key NSUnderlyingErrorKey can be used. * @return The converted Objective-C result. */ std::map user_info() const; diff --git a/include/generated/event.h b/include/generated/event.h index 7919d229..0f3643ff 100644 --- a/include/generated/event.h +++ b/include/generated/event.h @@ -495,15 +495,6 @@ namespace cocoon * @return The converted Objective-C result. */ double timestamp() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `touchSwipeNavigationEnabled` property of `NSEvent`. - * @details Returns the user's preference about using touch as a way to swipe between pages. This value is determined by the Touch preference panel for the current user. - * @return The converted Objective-C result. - */ - static bool is_touch_swipe_navigation_enabled(); -#endif - /** * @brief Returns the `trackingArea` property of `NSEvent`. * @details -trackingArea returns the NSTrackingArea that generated this event. It is possible for there to be no trackingArea associated with the event in some cases where the event corresponds to a trackingRect installed with -[NSView addTrackingRect:owner:userData:assumeInside:], in which case nil is returned. diff --git a/include/generated/exception.h b/include/generated/exception.h index b99fe949..78fa0da0 100644 --- a/include/generated/exception.h +++ b/include/generated/exception.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSException` (Foundation). - * @details An object that represents a special condition that interrupts the normal flow of program execution. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -43,7 +42,6 @@ namespace cocoon explicit Exception(Adopt adopt); /** * @brief Calls `-[NSException raise]`. - * @details Raises the receiver, causing program flow to jump to the local exception handler. */ void raise() const; template @@ -60,7 +58,6 @@ namespace cocoon static void raise_(const std::string& name, const std::string& format, const std::vector& args); /** * @brief Calls `+[NSException raise:format:arguments:]`. - * @details Creates and raises an exception with the specified name, reason format string, and 'va_list' of arguments. * @param name Argument converted to the Objective-C parameter of the same role. * @param format Argument converted to the Objective-C parameter of the same role. * @param arg_list Argument converted to the Objective-C parameter of the same role. @@ -68,31 +65,26 @@ namespace cocoon static void raise(const std::string& name, const std::string& format, char* arg_list); /** * @brief Returns the `callStackReturnAddresses` property of `NSException`. - * @details An array of return addresses from the call stack when the exception was first raised. * @return The converted Objective-C result. */ std::vector call_stack_return_addresses() const; /** * @brief Returns the `callStackSymbols` property of `NSException`. - * @details An array of strings describing the call stack backtrace at the point the exception was first raised. * @return The converted Objective-C result. */ std::vector call_stack_symbols() const; /** * @brief Returns the `name` property of `NSException`. - * @details A string used to uniquely identify the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Returns the `reason` property of `NSException`. - * @details A human-readable message string summarizing the reason for the exception. * @return The converted Objective-C result. */ std::string reason() const; /** * @brief Returns the `userInfo` property of `NSException`. - * @details A dictionary containing application-specific data pertaining to the receiver. * @return The converted Objective-C result. */ std::vector> user_info() const; diff --git a/include/generated/expression.h b/include/generated/expression.h index 6f60c81a..25c66565 100644 --- a/include/generated/expression.h +++ b/include/generated/expression.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSExpression` (Foundation). - * @details An expression for use in a comparison predicate. Comparison operations in an ''NSPredicate'' derive from two expressions as instances of the ''NSExpression'' class. You create expressions for constant values, key paths, and so on. Generally, anywhere in the ''NSExpression'' class hierarchy where there's a composite API and subtypes that may only reasonably respond to a subset of that API, invoking a method that doesn't make sense for that subtype throws an exception. \#\#\# Aggregate Expressions ''ExpressionType/aggregate'' allows you to create predicates containing expressions that evaluate to collections that contain further expressions. The collection may be an ''NSArray'', ''NSSet'', or ''NSDictionary'' object. Core Data doesn't support aggregate expressions. \#\#\# Subquery Expressions The ''ExpressionType/subquery'' creates a subexpression that returns a subset of a collection of objects. This allows you to create sophisticated queries across relationships, such as a search for multiple correlated values on the destination object of a relationship. \#\#\# Set Expressions The set expressions (''ExpressionType/unionSet'', ''ExpressionType/intersectSet'', and ''ExpressionType/minusSet'') combine results in a manner similar to the ''NSSet'' methods. Both sides of these expressions must evaluate to a collection; the left side must evaluate to an 'NSSet' object, and the right side can be any other collection type. '''objc (expression UNION expression) (expression INTERSECT expression) (expression MINUS expression) ''' Core Data doesn't support set expressions. \#\#\# Function Expressions In macOS 10.4, ''NSExpression'' only supports a predefined set of functions: 'sum', 'count', 'min', 'max', and 'average'. You access these predefined functions in the predicate syntax using custom keywords (for example, 'MAX(1, 5, 10)'). In macOS 10.5 and later, function expressions also support arbitrary method invocations. To implement this extended functionality, use the syntax 'FUNCTION(receiver, selectorName, arguments, ...),' as in the following example: '''objc FUNCTION(\@"/Developer/Tools/otest", \@"lastPathComponent") => \@"otest" ''' All methods must take one or more 'id' arguments and return an 'id' value, although you can use the 'CAST' expression to convert datatypes with lossy string representations (for example, 'CAST(\#\#\#\#, "NSDate")'). macOS 10.5 extends the 'CAST' expression to provide support for casting to classes for use in creating receivers for function expressions. Although Core Data supports evaluation of the predefined functions, it doesn't support the evaluation of custom predicate functions in the persistent stores (during a fetch). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -49,25 +48,21 @@ namespace cocoon explicit Expression(Adopt adopt); /** * @brief Calls `-[NSExpression allowEvaluation]`. - * @details Forces a securely decoded expression to allow evaluation. When securely decoding an 'NSExpression' object encoded using 'NSSecureCoding', evaluation is disabled because it is potentially unsafe to evaluate expressions you get out of an archive. Before you enable evaluation, you should validate key paths, selectors, etc to ensure no erroneous or malicious code will be executed. Once you've preflighted the expression, you can enable the expression for evaluation by calling 'allowEvaluation'. */ void allow_evaluation() const; /** * @brief Calls `+[NSExpression expressionForAggregate:]`. - * @details Creates an expression that returns a collection containing the results of other expressions. * @param subexpressions Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Expression expression_for_aggregate(const std::vector& subexpressions); /** * @brief Calls `+[NSExpression expressionForAnyKey]`. - * @details Creates an expression that represents any key for a Spotlight query. * @return The converted Objective-C result. */ static Expression expression_for_any_key(); /** * @brief Calls `+[NSExpression expressionForBlock:arguments:]`. - * @details Creates an expression that invokes a block with the parameters. * @param block Argument converted to the Objective-C parameter of the same role. * @param arguments Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -75,7 +70,6 @@ namespace cocoon static Expression expression_for_block(std::function, std::vector>)> block, const std::vector& arguments); /** * @brief Calls `+[NSExpression expressionForConditional:trueExpression:falseExpression:]`. - * @details Creates an expression that will return the result of trueExpression or falseExpression depending on the value of predicate. * @param predicate Argument converted to the Objective-C parameter of the same role. * @param true_expression Argument converted to the Objective-C parameter of the same role. * @param false_expression Argument converted to the Objective-C parameter of the same role. @@ -84,20 +78,17 @@ namespace cocoon static Expression expression_for_conditional(const Predicate& predicate, const Expression& true_expression, const Expression& false_expression); /** * @brief Calls `+[NSExpression expressionForConstantValue:]`. - * @details Creates an expression that returns a constant value. * @param obj Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Expression expression_for_constant_value(const Object& obj); /** * @brief Calls `+[NSExpression expressionForEvaluatedObject]`. - * @details Creates an expression that represents the object you're evaluating. * @return The converted Objective-C result. */ static Expression expression_for_evaluated_object(); /** * @brief Calls `+[NSExpression expressionForFunction:arguments:]`. - * @details Creates an expression that invokes one of the predefined functions. * @param name Argument converted to the Objective-C parameter of the same role. * @param parameters Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -105,7 +96,6 @@ namespace cocoon static Expression expression_for_function(const std::string& name, const std::vector& parameters); /** * @brief Calls `+[NSExpression expressionForFunction:selectorName:arguments:]`. - * @details Creates an expression that invokes a selector on a target with parameters. * @param target Argument converted to the Objective-C parameter of the same role. * @param name Argument converted to the Objective-C parameter of the same role. * @param parameters Argument converted to the Objective-C parameter of the same role. @@ -114,7 +104,6 @@ namespace cocoon static Expression expression_for_function(const Expression& target, const std::string& name, const std::vector& parameters); /** * @brief Calls `+[NSExpression expressionForIntersectSet:with:]`. - * @details Returns an expression that will return the intersection of the collections expressed by left and right. * @param left Argument converted to the Objective-C parameter of the same role. * @param right Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -122,14 +111,12 @@ namespace cocoon static Expression expression_for_intersect_set(const Expression& left, const Expression& right); /** * @brief Calls `+[NSExpression expressionForKeyPath:]`. - * @details Creates an expression that invokes the value function with a specified key path. - Parameters: - keyPath: The key path that the new expression should evaluate. - Returns: A new expression that invokes 'value(forKeyPath:)' with 'keyPath'. * @param key_path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Expression expression_for_key_path(const std::string& key_path); /** * @brief Calls `+[NSExpression expressionForMinusSet:with:]`. - * @details Returns an expression that will return the disjunction of the collections expressed by left and right. * @param left Argument converted to the Objective-C parameter of the same role. * @param right Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -137,7 +124,6 @@ namespace cocoon static Expression expression_for_minus_set(const Expression& left, const Expression& right); /** * @brief Calls `+[NSExpression expressionForSubquery:usingIteratorVariable:predicate:]`. - * @details Creates an expression that filters a collection using a subquery. * @param expression Argument converted to the Objective-C parameter of the same role. * @param variable Argument converted to the Objective-C parameter of the same role. * @param predicate Argument converted to the Objective-C parameter of the same role. @@ -146,7 +132,6 @@ namespace cocoon static Expression expression_for_subquery(const Expression& expression, const std::string& variable, const Predicate& predicate); /** * @brief Calls `+[NSExpression expressionForUnionSet:with:]`. - * @details Returns an expression that will return the union of the collections expressed by left and right. * @param left Argument converted to the Objective-C parameter of the same role. * @param right Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -154,14 +139,12 @@ namespace cocoon static Expression expression_for_union_set(const Expression& left, const Expression& right); /** * @brief Calls `+[NSExpression expressionForVariable:]`. - * @details Creates an expression that pulls a value from the variable bindings dictionary. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Expression expression_for_variable(const std::string& string); /** * @brief Calls `-[NSExpression expressionValueWithObject:context:]`. - * @details Evaluates an expression using a specified object and context. * @param object Argument converted to the Objective-C parameter of the same role. * @param context Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -169,85 +152,71 @@ namespace cocoon Object expression_value_with_object(const Object& object, const std::vector>& context) const; /** * @brief Returns the `arguments` property of `NSExpression`. - * @details The arguments for the expression. The array of expressions which will be passed as parameters during invocation of the selector on the operand of a function expression. * @return The converted Objective-C result. */ std::vector arguments() const; /** * @brief Returns the `collection` property of `NSExpression`. - * @details The collection of expressions in an aggregate expression, or the collection element of a subquery expression. * @return The converted Objective-C result. */ Object collection() const; /** * @brief Returns the `constantValue` property of `NSExpression`. - * @details The constant value of the expression. * @return The converted Objective-C result. */ Object constant_value() const; /** * @brief Returns the `expressionBlock` property of `NSExpression`. - * @details The block that executes to evaluate the expression. * @return The converted Objective-C result. */ std::function, std::vector>)> expression_block() const; /** * @brief Returns the `expressionType` property of `NSExpression`. - * @details The expression type for the expression. Accessing this property raises an exception if it is not applicable to the expression. * @return The converted Objective-C result. */ ExpressionType expression_type() const; /** * @brief Returns the `falseExpression` property of `NSExpression`. - * @details An expression to evaluate if a conditional expression's predicate evaluates to false. * @return The converted Objective-C result. */ Expression false_expression() const; /** * @brief Returns the `function` property of `NSExpression`. - * @details The function for the expression. * @return The converted Objective-C result. */ std::string function() const; /** * @brief Returns the `keyPath` property of `NSExpression`. - * @details The key path for the expression. * @return The converted Objective-C result. */ std::string key_path() const; /** * @brief Returns the `leftExpression` property of `NSExpression`. - * @details The left expression of an aggregate expression. * @return The converted Objective-C result. */ Expression left_expression() const; /** * @brief Returns the `operand` property of `NSExpression`. - * @details The operand for the expression. The operand is the object on which the expression's selector or block will be invoked. The object is the result of evaluating a key path or one of the defined functions. * @return The converted Objective-C result. */ Expression operand() const; /** * @brief Returns the `predicate` property of `NSExpression`. - * @details The predicate of a subquery expression. * @return The converted Objective-C result. */ Predicate predicate() const; /** * @brief Returns the `rightExpression` property of `NSExpression`. - * @details The right expression of an aggregate expression. * @return The converted Objective-C result. */ Expression right_expression() const; /** * @brief Returns the `trueExpression` property of `NSExpression`. - * @details An expression to evaluate if a conditional expression's predicate evaluates to true. * @return The converted Objective-C result. */ Expression true_expression() const; /** * @brief Returns the `variable` property of `NSExpression`. - * @details The variable for the expression. * @return The converted Objective-C result. */ std::string variable() const; diff --git a/include/generated/extension_context.h b/include/generated/extension_context.h index c2a377a7..ec42eb31 100644 --- a/include/generated/extension_context.h +++ b/include/generated/extension_context.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSExtensionContext` (Foundation). - * @details The host app context from which an app extension is invoked. When a host app sends a request to an app extension, it provides an extension context. For many app extensions, the most important part of the context is the data the user wants to work with, which is contained in the ''inputItems'' property. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -42,27 +41,23 @@ namespace cocoon explicit ExtensionContext(Adopt adopt); /** * @brief Calls `-[NSExtensionContext cancelRequestWithError:]`. - * @details Signals the host to cancel the app extension request, with the supplied error, which should be non-nil. The \@c userInfo of the \@c NSError will contain a key \@c NSExtensionItemsAndErrorsKey which will have as its value a dictionary of \@c NSExtensionItems and associated \@c NSError instances. * @param error Argument converted to the Objective-C parameter of the same role. */ void cancel_request_with_error(const Error& error) const; /** * @brief Calls `-[NSExtensionContext completeRequestReturningItems:completionHandler:]`. - * @details Signals the host to complete the app extension request with the supplied result items. The completion handler optionally contains any work which the extension may need to perform after the request has been completed, as a background-priority task. The \@c expired parameter will be \@c YES if the system decides to prematurely terminate a previous non-expiration invocation of the completion handler. Calling this method will eventually dismiss the associated view controller. * @param items Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void complete_request_returning_items(const std::vector& items, std::function completion_handler) const; /** * @brief Calls `-[NSExtensionContext openURL:completionHandler:]`. - * @details Asks the host to open a URL on the extension's behalf. * @param url Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void open_url(const URL& url, std::function completion_handler) const; /** * @brief Returns the `inputItems` property of `NSExtensionContext`. - * @details The list of input NSExtensionItems associated with the context. If the context has no input items, this array will be empty. * @return The converted Objective-C result. */ std::vector input_items() const; diff --git a/include/generated/extension_item.h b/include/generated/extension_item.h index 40d8830a..2a0a0a17 100644 --- a/include/generated/extension_item.h +++ b/include/generated/extension_item.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSExtensionItem` (Foundation). - * @details An immutable collection of values representing different aspects of an item for an extension to act upon. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,49 +44,41 @@ namespace cocoon explicit ExtensionItem(Adopt adopt); /** * @brief Returns the `attachments` property of `NSExtensionItem`. - * @details Optional array of media data associated with the extension item, including images, videos, and URLs. This is not meant to be an array of alternate data formats/types, but instead a collection to include in a social media post for example. * @return The converted Objective-C result. */ std::vector attachments() const; /** * @brief Sets the `attachments` property of `NSExtensionItem`. - * @details Optional array of media data associated with the extension item, including images, videos, and URLs. This is not meant to be an array of alternate data formats/types, but instead a collection to include in a social media post for example. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attachments(const std::vector& value) const; /** * @brief Returns the `attributedContentText` property of `NSExtensionItem`. - * @details Optional content text. * @return The converted Objective-C result. */ AttributedString attributed_content_text() const; /** * @brief Sets the `attributedContentText` property of `NSExtensionItem`. - * @details Optional content text. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attributed_content_text(const AttributedString& value) const; /** * @brief Returns the `attributedTitle` property of `NSExtensionItem`. - * @details An optional title for the item. * @return The converted Objective-C result. */ AttributedString attributed_title() const; /** * @brief Sets the `attributedTitle` property of `NSExtensionItem`. - * @details An optional title for the item. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attributed_title(const AttributedString& value) const; /** * @brief Returns the `userInfo` property of `NSExtensionItem`. - * @details Optional dictionary of key-value data. The key/value pairs accepted by the service are expected to be specified in the extension's \@c Info.plist. The values of \@c NSExtensionItem's properties will be reflected into the dictionary. * @return The converted Objective-C result. */ std::vector> user_info() const; /** * @brief Sets the `userInfo` property of `NSExtensionItem`. - * @details Optional dictionary of key-value data. The key/value pairs accepted by the service are expected to be specified in the extension's \@c Info.plist. The values of \@c NSExtensionItem's properties will be reflected into the dictionary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_user_info(const std::vector>& value) const; diff --git a/include/generated/file_access_intent.h b/include/generated/file_access_intent.h index 87482a81..0172a379 100644 --- a/include/generated/file_access_intent.h +++ b/include/generated/file_access_intent.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFileAccessIntent` (Foundation). - * @details The details of a coordinated-read or coordinated-write operation. Use this class when performing asynchronous operations with a file coordinator using the coordinator's ''NSFileCoordinator/coordinate(with:queue:byAccessor:)'' method. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -42,7 +41,6 @@ namespace cocoon explicit FileAccessIntent(Adopt adopt); /** * @brief Calls `+[NSFileAccessIntent readingIntentWithURL:options:]`. - * @details Returns a file access intent object for reading the given URL with the provided options. When calling a file coordinator's ''NSFileCoordinator/coordinate(with:queue:byAccessor:)'' method, you pass an array of file access intent objects. Each intent object represents a specific read or write operation on a single document or directory. Use this method to create an intent object suitable for reading. - Parameters: - url: The URL of the document you intend to read from. - options: The coordinated reading options. For a list of valid values, see ''NSFileCoordinator/ReadingOptions'' in the ''NSFileCoordinator''. - Returns: A newly instantiated and configured file access intent object. * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -50,7 +48,6 @@ namespace cocoon static FileAccessIntent reading_intent_with_url(const URL& url, FileCoordinatorReadingOptions options); /** * @brief Calls `+[NSFileAccessIntent writingIntentWithURL:options:]`. - * @details Returns a file access intent object for writing to the given URL with the provided options. When calling a file coordinator's ''NSFileCoordinator/coordinate(with:queue:byAccessor:)'' method, you pass an array of file access intent objects. Each intent object represents a specific read or write operation on a single document or directory. Use this method to create an intent object suitable for writing. - Parameters: - url: The URL of the document you intend to write to. - options: The coordinated writing options. For a list of valid values, see ''NSFileCoordinator/WritingOptions'' in the ''NSFileCoordinator''. - Returns: A newly instantiated and configured file access intent object. * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -58,7 +55,6 @@ namespace cocoon static FileAccessIntent writing_intent_with_url(const URL& url, FileCoordinatorWritingOptions options); /** * @brief Returns the `URL` property of `NSFileAccessIntent`. - * @details The URL of the item. Use this URL within the accessor block. This property may change from its original value in response to actions from other writers. * @return The converted Objective-C result. */ URL url() const; diff --git a/include/generated/file_coordinator.h b/include/generated/file_coordinator.h index 1b59f9c5..6c183b2d 100644 --- a/include/generated/file_coordinator.h +++ b/include/generated/file_coordinator.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFileCoordinator` (Foundation). - * @details An object that coordinates the reading and writing of files and directories among file presenters. The ''NSFileCoordinator'' class coordinates the reading and writing of files and directories among multiple processes and objects in the same process. You use instances of this class as is to read from, write to, modify the attributes of, change the location of, or delete a file or directory, but before your code to perform those actions executes, the file coordinator lets registered file presenter objects perform any tasks that they might require to ensure their own integrity. For example, if you want to change the location of a file, other objects interested in that file need to know where you intend to move it so that they can update their references. Objects that adopt the ''NSFilePresenter'' protocol must register themselves with the ''NSFileCoordinator'' class to be notified of any pending changes. They do this by calling the ''addFilePresenter(:)'' class method. A file presenter must balance calls to ''addFilePresenter(:)'' with a call to ''removeFilePresenter(:)'' before being released, even in a garbage-collected application. The file presenter class maintains a list of active file presenter objects in the current application and uses that list, plus the file coordinator classes in other processes, to deliver notifications to all of the objects interested in a particular item. Instances of ''NSFileCoordinator'' are meant to be used on a per-file-operation basis, where a file operation is something like opening and reading the contents of a file or moving a batch of files and directories to a new location. There is no benefit to keeping a file coordinator object past the length of the planned operation. In fact, because file coordinators retain file presenter objects, keeping one around could prevent the file presenter objects from being released in a timely manner. For information about implementing a file presenter object to receive file-related notifications, see ''NSFilePresenter''. \#\#\# File Presenters and iOS If your app or extension enters the background with an active file presenter, it may be terminated by the system in order to prevent deadlock on that file. To prevent this situation, call ''removeFilePresenter(:)'' to remove the file presenter in the \ method or in response to a \ notification. Call ''addFilePresenter(:)'' to add the file presenter again in the \ method or in response to a \ notification. > Note: > The \ class automatically removes itself when your app goes to the background. It automatically adds itself again when your app returns to the foreground. \#\#\# File Coordinators and iOS A coordinated read or write will automatically begin a background task when granted, similar to one created with the \ method. This helps ensure that your app or extension has sufficient time to finish the read or write operation if it's suspended, without creating a deadlock on access to that file by other processes. If a process is suspended while waiting for a coordinated read or write to be granted, the request is canceled, and an 'NSError' object with the code ''NSUserCancelledError-var'' is produced. If the background task expires, the process is terminated. > Note: > The \ class automatically requests additional background time and safely performs coordinated reads and writes when loading and saving the document. \#\#\# Threading Considerations Each file coordinator object you create should be used on a single thread only. If you need to coordinate file operations across multiple objects in different threads, each object should create its own file coordinator. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -51,18 +50,18 @@ namespace cocoon explicit FileCoordinator(Adopt adopt); /** * @brief Calls `+[NSFileCoordinator addFilePresenter:]`. - * @details Registers the specified file presenter object so that it can receive notifications. This method registers the file presenter object process wide. Thus, any file coordinator objects you create later automatically know about the file presenter object and know to message it when its file or directory is affected. Be sure to balance calls to this method with a corresponding call to +removeFilePresenter: before the file presenter is deallocated, even in a garbage-collected application. If you call this method while coordinated file operations are already under way in another process, your file presenter may not receive notifications for that operation. To prevent missing such notifications, create a file coordinator, call its -coordinateReadingItemAtURL:options:error:byAccessor: method, and register your file presenter object there. If you are going to read a file and then create a file presenter for that file, both actions should occur in the same coordinated read block. Synchronizing on the presented file or directory guarantees that when your block executes, all other objects have completed any tasks and you have sole access to the item. + * @details The process' file presenters. If you invoke +addFilePresenter: you have to do a balancing invocation of +removeFilePresenter: before the file presenter is deallocated, even in a garbage-collected application. If your application reads an item and then registers a file presenter for it there is a possible race condition in which between those two steps another process does coordinated reading or writing of the item, without any messages sent to your not-quite-registered file presenter. This can leave your file presenter ignorant of the fact that what it knows about the item it just read is already out of date, or under the misconception that just because it hasn't received a -relinquish... method it owns the item. To avoid that race condition you can invoke +addFilePresenter: in the same block that you pass to -coordinateReadingItemAtURL:options:error:byAccessor: to read what the file presenter will present. * @param file_presenter Argument converted to the Objective-C parameter of the same role. */ static void add_file_presenter(const Object& file_presenter); /** * @brief Calls `-[NSFileCoordinator cancel]`. - * @details Cancels any active file coordination calls. Use this method to cancel any active calls to coordinate the reading or writing of a file. If the block passed to the file coordination call has not yet been executed — perhaps because the file coordinator is still waiting for a response from other file presenters — the file coordinator method stops waiting for a response, does not execute its block, and returns an error object with the error code NSUserCancelledError. However, if the block is already being executed, the file coordinator method does not return until the block finishes executing. You can call this method from any thread of your application and it returns immediately without waiting for the file coordinator object to respond. Thus, when this method returns, you cannot assume that the read or write operation occurred or did not occur. If you want to know whether the operation actually occurred, you must track it yourself by setting a flag when the block starts executing or by using some other means. + * @details Cancel all invocations of -coordinate... and -prepare... methods for the receiver. Any current invocation of one of those methods will stop waiting and return immediately, unless it has already invoked the passed-in block, in which case it will return when the passed-in block returns. Subsequent invocations of those methods will not invoke the blocks passed into them at all. When an invocation of -coordinate... or -prepare... returns without invoking the passed-in block because this method was invoked it instead returns an error whose domain is NSCocoaErrorDomain and whose code is NSUserCancelledError. Messages that have already been sent to NSFilePresenters will not be cancelled but the file coordination machinery will stop waiting for the replies. This method can be invoked from any thread. It always returns immediately, without waiting for anything. Cancellation is racy; you usually cannot assume that no block passed into a -coordinate... or -prepare... method is already being invoked, so the code inside those blocks typically still has to check for cancellation, whatever that means in your application. */ void cancel() const; /** * @brief Calls `-[NSFileCoordinator coordinateAccessWithIntents:queue:byAccessor:]`. - * @details Performs a number of coordinated-read or -write operations asynchronously. This method lets you asynchronously perform coordinated read or writes. You can specify any combination of individual read or write operations. The file coordinator waits asynchronously to get access to the files and then invokes the accessor block on the specified queue. If an error occurs while waiting for access, an error message is passed to the block. You must check the block's error parameter before accessing any of the files. If the error parameter is set to nil, you can freely perform the read and write operations described by your intents. Otherwise, you may not access the files. Additionally, always use the URL property on the NSFileAccessIntent objects when accessing the files inside the accessor block. The system updates this property to account for any changes to the underlying files. Your file coordinator has access to the files only until the accessor block returns. Do not dispatch tasks that continue to access these files onto other threads or queues. In general a coordinated reader waits for a coordinated writer of the same item, and a coordinated writer waits for coordinated readers and other coordinated writers of the same item. Coordinated readers do not wait for each other. Coordinated reading or writing of items in a file package is treated as coordinated reading or writing of the file package as a whole. Coordinated reads and writes from the same file coordinator instance never block each other. However, if you make multiple, concurrent calls to this method, you risk deadlocking with another process that is similarly making multiple concurrent calls. Wherever possible, invoke this method once with multiple file access intent objects. + * @details Given an array of one or more NSFileAccessIntent objects that specify reading and/or writing items located by the corresponding URLs, wait asynchronously for certain other readers and writers and then invoke the passed-in block on the given queue, which must not be nil. If an error occurs, file access is not granted and a non-nil error will be passed to the accessor block. If file access is successfully granted, then 'error' will be nil and you may perform the intended file access inside the accessor block. You must use the URL property on the NSFileAccessIntent objects when performing file access in the accessor block. Within the block, the NSFileAccessIntent objects' URLs may differ from their original values to account for items that have been moved or renamed while waiting for access to be granted. When access to the intended files is granted, certain other readers and writers are made to wait until the given block returns, which defines the end of that file access. Do not allow file access to continue after the accessor block returns by dispatching work to other threads or queues. You can invoke this method to serialize your process's access of files and directories with other processes' access of the same files and directories so that inconsistencies due to overlapping reading and writing don't occur. It also causes messages to be sent to NSFilePresenters, and wait for NSFilePresenters to react, as described below. The fact that file system items can be moved or renamed while this method is waiting to invoke the block you passed when invoking it is why it's critical to use the URL property on the NSFileAccessIntent objects, not the URLs you used when initializing them. In general a coordinated reader waits for a coordinated writer of the same item, and a coordinated writer waits for coordinated readers and other coordinated writers of the same item. Coordinated readers do not wait for each other. Coordinated reading or writing of items in a file package is treated as coordinated reading or writing of the file package as a whole. A coordinated reader of a directory that is not a file package does not wait for coordinated writers of contained items, or cause such writers to wait. With one exception, a coordinated writer of a directory that is not a file package does not wait for coordinated readers and writers of contained items, or cause such readers and writers to wait. The exception is when you use NSFileCoordinatorWritingForDeleting, NSFileCoordinatorWritingForMoving, or NSFileCoordinatorWritingForReplacing. They make your coordinated writer wait for previously scheduled coordinated readers and writers of contained items, and causes subsequently scheduled coordinated readers and writers of contained items to wait. None of those rules apply to coordinated readers and writers that are using the exact same instance of NSFileCoordinator, including arrays of multiple NSFileAccessIntent objects. Instances of NSFileCoordinator never block themselves. You can take advantage of that in a couple of ways when invoking -coordinateAccessWithIntents:queue:byAccessor: multiple times on the same NSFileCoordinator instance, but take care because doing so raises the possibility of deadlocking with other processes that are doing the same sort of thing. If you can, you should invoke -coordinateAccessWithIntents:queue:byAccessor: a single time with multiple NSFileAccessIntent objects instead of invoking it multiple times with a single NSFileAccssIntent object. In addition to waiting for writers, readers wait for NSFilePresenters that are messaged as part of the coordinated reading. Coordinated reading of an item triggers the sending of messages to NSFilePresenters that implement the corresponding optional methods, even those in other processes, except the one specified when -initWithFilePresenter: was invoked: - -relinquishPresentedItemToReader: is sent to NSFilePresenters of the item and, if the item is in a file package, NSFilePresenters of the file package. If there are nested file packages then the message is sent to NSFilePresenters of all of them. - If NSFileCoordinatorReadingWithoutChanges is not used then -savePresentedItemChangesWithCompletionHandler: is also sent to the same NSFilePresenters. In addition to waiting for readers and other writers, writers wait for NSFilePresenters that are messaged as part of the coordinated writing. Coordinated writing of an item triggers the sending of messages to NSFilePresenters that implement the corresponding optional methods, even those in other processes, except the one specified when -initWithFilePresenter: was invoked: - -relinquishPresentedItemToWriter: is sent to NSFilePresenters of the item and, if the item is in a file package, NSFilePresenters of the file package. If there are nested file packages then the message is sent to NSFilePresenters of all of them. - If NSFileCoordinatorWritingForDeleting, NSFileCoordinatorWritingForMoving, or NSFileCoordinatorWritingForReplacing is used and the item is a directory then -relinquishPresentedItemToWriter: is also sent to NSFilePresenters of each item contained by it. - If NSFileCoordinatorWritingForDeleting or NSFileCoordinatorWritingForReplacing is used then -accommodatePresentedItemDeletionWithCompletionHandler: is sent to NSFilePresenters of the item and, if the item is a directory, NSFilePresenters of each item contained by it. -accommodatePresentedSubitemDeletionAtURL:completionHandler: is sent to NSFilePresenters of each file package that contains the item. - When NSFileCoordinatorWritingForReplacing is used the the definition of "the item" depends on what happened while waiting for other writers. See the description of it above. - If NSFileCoordinatorWritingForMerging is used then -savePresentedItemChangesWithCompletionHandler: is sent to NSFilePresenters of the item and, if the item is in a file package, NSFilePresenters of the file package. If there are nested file packages then the message is sent to NSFilePresenters of all of them. For both coordinated reading and writing, if there are multiple NSFilePresenters involved then the order in which they are messaged is undefined. If an NSFilePresenter signals failure then waiting will fail and outError will be set to an NSError describing the failure. * @param intents Argument converted to the Objective-C parameter of the same role. * @param queue Argument converted to the Objective-C parameter of the same role. * @param accessor Argument converted to the Objective-C parameter of the same role. @@ -70,7 +69,7 @@ namespace cocoon void coordinate_access_with_intents(const std::vector& intents, const OperationQueue& queue, std::function accessor) const; /** * @brief Calls `-[NSFileCoordinator coordinateReadingItemAtURL:options:error:byAccessor:]`. - * @details Initiates a read operation on a single file or directory using the specified options. This method executes synchronously, blocking the current thread until the reader block finishes executing. Before executing that block, the file coordinator waits until other relevant file presenter objects finish in-progress actions. When invoking these methods, declare a block variable before the accessor block and initialize it to a value that signals failure, and then inside the accessor block set it to a value that indicates success. If the coordinated operation fails, then the accessor block never runs and the NSError out parameter contains a reference that describes the error. This method calls the -relinquishPresentedItemToReader: method of any relevant file presenters. Depending on the options you specify, other methods of the file presenters may also be called. All of the called methods must return successfully before the file coordinator executes your block. If multiple file presenters are operating on the item, the order in which those presenters are notified is undefined. If the device has not yet downloaded the file at the given URL, this method blocks (potentially for a long time) while the file is downloaded. + * @details The next four methods behave similarly to -coordinateAccessWithIntents:queue:byAccessor: with one or two NSFileAccessIntent objects with the following exceptions: Each of these methods wait synchronously on the same thread they were invoked on before invoking the passed-in accessor block on the same thread, instead of waiting asynchronously and scheduling invocation of the block on a specific queue. The accessor block of each of these methods is passed one or more URLs that locate the intended items, perhaps changed from the original URLs to take into account the fact that the item might have been moved or renamed during the waiting. Each of these methods returns an NSError by reference instead of passing it to the accessory block. However, these methods are uncommon among Cocoa framework methods in that they don't also return a result indicating success or failure. The success of the waiting that they do is typically not interesting to invokers. Only the success of file system access done by the passed-in block is interesting. (The failure of either is of course interesting.) When invoking these methods it's cleanest to just declare a block variable outside of the block and initialize it to a value that signals failure, and then inside the block set it to a value that signals success. If the waiting fails then the invoked method sets the error reference to an NSError that describes what went wrong, your block will not be invoked, your block variable will not be set to a value that signals success, and all will be as it should be, with failure signaled and an NSError that describes the failure. * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param reader Argument converted to the Objective-C parameter of the same role. @@ -78,7 +77,6 @@ namespace cocoon void coordinate_reading_item_at_url(const URL& url, FileCoordinatorReadingOptions options, std::function reader) const; /** * @brief Calls `-[NSFileCoordinator coordinateReadingItemAtURL:options:writingItemAtURL:options:error:byAccessor:]`. - * @details Initiates a read operation that contains a follow-up write operation. You use this method to perform a read operation that might also contain a write operation that needs to be coordinated. This method executes synchronously, blocking the current thread until the readerWriter block finishes executing. When performing the write operation, you may call -coordinateWritingItemAtURL:options:error:byAccessor: from your readerWriter block. This method does the canonical lock ordering that is required to prevent a potential deadlock of the file operations. When invoking this method, declare a block variable before the accessor block and initialize it to a value that signals failure, and then inside the accessor block set it to a value that indicates success. If the coordinated operation fails, then the accessor block never runs and the NSError out parameter contains a reference that describes the error. This method makes the same calls to file presenters, and has the same general wait behavior, as the -coordinateReadingItemAtURL:options:error:byAccessor: and -coordinateWritingItemAtURL:options:error:byAccessor: methods. * @param reading_url Argument converted to the Objective-C parameter of the same role. * @param reading_options Argument converted to the Objective-C parameter of the same role. * @param writing_url Argument converted to the Objective-C parameter of the same role. @@ -88,7 +86,6 @@ namespace cocoon void coordinate_reading_item_at_url(const URL& reading_url, FileCoordinatorReadingOptions reading_options, const URL& writing_url, FileCoordinatorWritingOptions writing_options, std::function reader_writer) const; /** * @brief Calls `-[NSFileCoordinator coordinateWritingItemAtURL:options:error:byAccessor:]`. - * @details Initiates a write operation on a single file or directory using the specified options. This method executes synchronously, blocking the current thread until the writer block finishes executing. Before executing the block, the file coordinator waits until other relevant file presenter objects finish in-progress actions. When invoking this method, declare a block variable before the accessor block and initialize it to a value that signals failure, and then inside the accessor block set it to a value that indicates success. If the coordinated operation fails, then the accessor block never runs and the NSError out parameter contains a reference that describes the error. This method calls the -relinquishPresentedItemToWriter: method of any relevant file presenters. Depending on the options you specify, other methods of the file presenters may also be called. All of the called methods must return successfully before the file coordinator executes your block. With one exception, do not nest calls to file coordinator methods inside the block you pass to this method. You may call -coordinateReadingItemAtURL:options:error:byAccessor: to read the file if you discover through modification-date checking that the contents of the file have changed. However, if you call this method from inside your block, the file coordinator object throws an exception. * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param writer Argument converted to the Objective-C parameter of the same role. @@ -96,7 +93,6 @@ namespace cocoon void coordinate_writing_item_at_url(const URL& url, FileCoordinatorWritingOptions options, std::function writer) const; /** * @brief Calls `-[NSFileCoordinator coordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor:]`. - * @details Initiates a write operation that involves a secondary write operation. You use this method to perform two write operations without the risk of those operations creating a deadlock. This method executes synchronously, blocking the current thread until the writer block finishes executing. You may call -coordinateWritingItemAtURL:options:error:byAccessor: from your writer block. This method does the canonical lock ordering that is required to prevent a potential deadlock of the file operations. When invoking this method, declare a block variable before the accessor block and initialize it to a value that signals failure, and then inside the accessor block set it to a value that indicates success. If the coordinated operation fails, then the accessor block never runs and the NSError out parameter contains a reference that describes the error. This method makes the same calls to file presenters, and has the same general wait behavior, as the -coordinateWritingItemAtURL:options:error:byAccessor: method. * @param url1 Argument converted to the Objective-C parameter of the same role. * @param options1 Argument converted to the Objective-C parameter of the same role. * @param url2 Argument converted to the Objective-C parameter of the same role. @@ -106,21 +102,21 @@ namespace cocoon void coordinate_writing_item_at_url(const URL& url1, FileCoordinatorWritingOptions options1, const URL& url2, FileCoordinatorWritingOptions options2, std::function writer) const; /** * @brief Calls `-[NSFileCoordinator itemAtURL:didChangeUbiquityAttributes:]`. - * @details Tells observing file providers that the item's ubiquity attributes have changed. This triggers the -presentedItemDidChangeUbiquityAttributes: method on any file presenters that are observing the item, even if they are running in different processes. See NSFilePresenter's observedPresentedItemUbiquityAttributes property for an explanation of valid attributes. + * @details Announce that the item located by a URL has changed one or more ubiquity attributes. See NSFilePresenter.observedPresentedItemUbiquityAttributes for an explanation of valid attributes. This triggers the sending of messages to NSFilePresenters that implement -presentedItemDidChangeUbiquityAttibutes:, even those in other processes. * @param url Argument converted to the Objective-C parameter of the same role. * @param attributes Argument converted to the Objective-C parameter of the same role. */ void item_at_url(const URL& url, const std::vector& attributes) const; /** * @brief Calls `-[NSFileCoordinator itemAtURL:didMoveToURL:]`. - * @details Notifies relevant file presenters that the location of a file or directory changed. If you move or rename a file or directory as part of a write operation, call this method to notify relevant file presenters that the change occurred. This method calls -presentedItemDidMoveToURL: for any of the item's file presenters. If the item is a directory, this method calls -presentedItemDidMoveToURL: on the file presenters for the item's contents. Finally, it calls -presentedSubitemAtURL:didMoveToURL: on the file presenter of any directory containing the item. You must call this method from a coordinated write block. Calling this method with the same URL in the oldURL and newURL parameters is harmless. This call must balance a call to -itemAtURL:willMoveToURL:. + * @details Announce that the item located by a URL is now located by another URL. This triggers the sending of messages to NSFilePresenters that implement the corresponding optional methods, even those in other processes, except the one specified when -initWithFilePresenter: was invoked: - -presentedItemDidMoveToURL: is sent to NSFilePresenters of the item. - If the item is a directory then -presentedItemDidMoveToURL: is sent to NSFilePresenters of each item contained by it. - -presentedSubitemAtURL:didMoveToURL: is sent to NSFilePresenters of each directory that contains the item, unless that method is not implemented but -presentedItemDidChange is, and the directory is actually a file package, in which case -presentedItemDidChange is sent instead. This also balances invocations of -itemAtURL:willMoveToURL:, as described above. Useless invocations of this method are harmless, so you don't have to write code that compares NSURLs for equality, which is not straightforward. This method must be invoked from within the block passed to an invocation of -coordinateAccessWithIntents:queue:byAccessory:, -coordinateWritingItemAtURL:options:error:byAccessor:, or -coordinateReadingItemAtURL:options:writingItemAtURL:options:error:byAccessor:. * @param old_url Argument converted to the Objective-C parameter of the same role. * @param new_url Argument converted to the Objective-C parameter of the same role. */ void item_at_url(const URL& old_url, const URL& new_url) const; /** * @brief Calls `-[NSFileCoordinator prepareForReadingItemsAtURLs:options:writingItemsAtURLs:options:error:byAccessor:]`. - * @details Prepare to read or write from multiple files in a single batch operation. Use this method to prepare the file coordinator for multiple read and write operations. Because file coordination requires interprocess communication, it is much more efficient to batch changes to large numbers of files and directories than to change each item individually. The file coordinator uses the values in the readingURLs and writingURLs parameters, together with reading and writing options, to prepare any relevant file presenters for the upcoming operations. This method executes synchronously, blocking the current thread until the batchAccessor block finishes executing. The batchAccessor block you provide does not have exclusive access to the given items when it is invoked. Instead, you must call coordinated read and write methods for each individual item from inside the batchAccessor block. You must then call the completion handler after all the coordinated reads and writes have completed. You can call the completion handler from any thread. Don't simply pass this method all the URLs that are passed into the nested coordinate methods. Instead pass only the top-level files and directories involved in the operation. This method triggers messages to the file presenters of those items and to the file presenters of any items contained by those items. In most cases, passing the same reading and writing options to both this method and the contained coordination operations is redundant. + * @details Prepare to more efficiently do a large number of invocations of -coordinate... methods, first synchronously messaging and waiting for NSFilePresenters in a variation of what individual invocations of the -coordinate... methods would do, and then, if no error occurs, invoke the passed-in block. The passed-in block must invoke the completion handler passed to it when all of the coordinated reading and writing it does is done. The completion handler block can be invoked on any thread (or from any dispatch queue, if that's how you think of it). This method returns errors in the same manner as the -coordinate... methods. The -coordinate... methods must use interprocess communication to message instances of NSFileCoordinator and NSFilePresenter in other processes in the system. That is an expense best avoided when reading or writing many files in one operation. Using this method can greatly reduce the amount of interprocess communication required by, for example, a large batched copying or moving of files. You use it by moving all of the invocations of the -coordinate... methods your application will do during a batch operation, or the scheduling of them if the operation's work is done in a multithreaded fashion, into a block and passing that block to an invocation of this method, remembering that the completion handler passed to that block must be invoked when the operation is done. You don't simply pass all URLs that will be passed into invocations of the -coordinate... methods when invoking this method. Instead you pass the top-level files and directories involved in the operation. This method triggers messages to not just NSFilePresenters of those items, but also NSFilePresenters of items contained by those items. For example, when Finder uses this method during a copy operation readingURLs is an array of the URLs of the exact files and folders that the user has selected, even though those folders may contain many files and subfolders for which Finder is going to do coordinated reading, and writingURLs is an array that contains just the URL of the destination folder. In most cases it is redundant to pass the same reading or writing options in an invocation of this method as are passed to individual invocations of the -coordinate... methods invoked by the block passed to an invocation of this method. For example, when Finder invokes this method during a copy operation it does not pass NSFileCoordinatorReadingWithoutChanges because it is appropriate to trigger the saving of document changes right away, but it does pass it when doing the nested invocations of -coordinate... methods because it is not necessary to trigger saving again, even if the user changes the document before the Finder proceeds far enough to actually copy that document's file. * @param reading_urls Argument converted to the Objective-C parameter of the same role. * @param reading_options Argument converted to the Objective-C parameter of the same role. * @param writing_urls Argument converted to the Objective-C parameter of the same role. @@ -130,25 +126,23 @@ namespace cocoon void prepare_for_reading_items_at_urls(const std::vector& reading_urls, FileCoordinatorReadingOptions reading_options, const std::vector& writing_urls, FileCoordinatorWritingOptions writing_options, std::function)> batch_accessor) const; /** * @brief Calls `+[NSFileCoordinator removeFilePresenter:]`. - * @details Unregisters the specified file presenter object. Call this method to unregister file presenters before those objects are deallocated. * @param file_presenter Argument converted to the Objective-C parameter of the same role. */ static void remove_file_presenter(const Object& file_presenter); /** * @brief Returns the `filePresenters` property of `NSFileCoordinator`. - * @details Returns an array containing the process's currently registered file presenter objects. * @return The converted Objective-C result. */ static std::vector file_presenters(); /** * @brief Returns the `purposeIdentifier` property of `NSFileCoordinator`. - * @details A string that uniquely identifies the file access that was performed by this file coordinator. Every NSFileCoordinator has a unique purpose identifier that is created during initialization. Coordinated reads and writes performed by NSFileCoordinators with the same purpose identifier never block each other, even if they exist in different processes. If you are coordinating file access on behalf of a file presenter, use -initWithFilePresenter: and do not attempt to set a custom purpose identifier. Every file coordinator instance initialized with the same file presenter has the same purpose identifier. You may need to set a custom purpose identifier for the following reasons: - Your application has a File Provider extension. Any file coordination done on behalf of the File Provider needs to be done using the File Provider's purpose identifier. - You have two separate subsystems that need to work together to perform a single high-level operation, and both subsystems perform their own coordinated reads or writes. Using the same purpose identifier in both subsystems prevents possible deadlocks between the two subsystems. When creating custom purpose identifiers, you can use a reverse DNS style string, such as "com.mycompany.myapplication.mypurpose", or a UUID string. Nil and zero-length strings are not allowed. Purpose identifiers can be set only once. If you attempt to set the purpose identifier of an NSFileCoordinator that you initialized with -initWithFilePresenter: or that you already assigned a purpose identifier, an exception will be thrown. + * @details A string that uniquely identifies the file access that will be done by this NSFileCoordinator. Every NSFileCoordinator has a unique purpose identifier that is created during initialization. Coordinated reads and writes performed by NSFileCoordinators with the same purpose identifier never block each other, even if they exist in different processes. In addition to some of the reasons explained in the comments of -initWithFilePresenter:, you may want to set a custom purpose identifier for the following reasons: - Your application has an NSFileProviderExtension. Any file coordination done on behalf of the NSFileProviderExtension needs to be done using the same purpose identifier reported by your NSFileProviderExtension. - To avoid deadlocking when two separate subsystems need to work together to perform one high-level operation, and both subsystems perform their own coordinated reads or writes. If you are coordinating file access on behalf of an NSFilePresenter, you should use -initWithFilePresenter: and should not attempt to set a custom purpose identifier. Every NSFileCoordinator instance initialized with the same NSFilePresenter will have the same purpose identifier. When creating custom purpose identifiers, you can use a reverse DNS style string, such as "com.mycompany.myapplication.mypurpose", or a UUID string. Nil and zero-length strings are not allowed. Purpose identifiers can be set only once. If you attempt to set the purpose identifier of an NSFileCoordinator that you initialized with -initWithFilePresenter: or that you already assigned a purpose identifier, an exception will be thrown. * @return The converted Objective-C result. */ std::string purpose_identifier() const; /** * @brief Sets the `purposeIdentifier` property of `NSFileCoordinator`. - * @details A string that uniquely identifies the file access that was performed by this file coordinator. Every NSFileCoordinator has a unique purpose identifier that is created during initialization. Coordinated reads and writes performed by NSFileCoordinators with the same purpose identifier never block each other, even if they exist in different processes. If you are coordinating file access on behalf of a file presenter, use -initWithFilePresenter: and do not attempt to set a custom purpose identifier. Every file coordinator instance initialized with the same file presenter has the same purpose identifier. You may need to set a custom purpose identifier for the following reasons: - Your application has a File Provider extension. Any file coordination done on behalf of the File Provider needs to be done using the File Provider's purpose identifier. - You have two separate subsystems that need to work together to perform a single high-level operation, and both subsystems perform their own coordinated reads or writes. Using the same purpose identifier in both subsystems prevents possible deadlocks between the two subsystems. When creating custom purpose identifiers, you can use a reverse DNS style string, such as "com.mycompany.myapplication.mypurpose", or a UUID string. Nil and zero-length strings are not allowed. Purpose identifiers can be set only once. If you attempt to set the purpose identifier of an NSFileCoordinator that you initialized with -initWithFilePresenter: or that you already assigned a purpose identifier, an exception will be thrown. + * @details A string that uniquely identifies the file access that will be done by this NSFileCoordinator. Every NSFileCoordinator has a unique purpose identifier that is created during initialization. Coordinated reads and writes performed by NSFileCoordinators with the same purpose identifier never block each other, even if they exist in different processes. In addition to some of the reasons explained in the comments of -initWithFilePresenter:, you may want to set a custom purpose identifier for the following reasons: - Your application has an NSFileProviderExtension. Any file coordination done on behalf of the NSFileProviderExtension needs to be done using the same purpose identifier reported by your NSFileProviderExtension. - To avoid deadlocking when two separate subsystems need to work together to perform one high-level operation, and both subsystems perform their own coordinated reads or writes. If you are coordinating file access on behalf of an NSFilePresenter, you should use -initWithFilePresenter: and should not attempt to set a custom purpose identifier. Every NSFileCoordinator instance initialized with the same NSFilePresenter will have the same purpose identifier. When creating custom purpose identifiers, you can use a reverse DNS style string, such as "com.mycompany.myapplication.mypurpose", or a UUID string. Nil and zero-length strings are not allowed. Purpose identifiers can be set only once. If you attempt to set the purpose identifier of an NSFileCoordinator that you initialized with -initWithFilePresenter: or that you already assigned a purpose identifier, an exception will be thrown. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_purpose_identifier(const std::string& value) const; diff --git a/include/generated/file_handle.h b/include/generated/file_handle.h index 79562aa1..2f1a0ef6 100644 --- a/include/generated/file_handle.h +++ b/include/generated/file_handle.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFileHandle` (Foundation). - * @details An object-oriented wrapper for a file descriptor. You use file handle objects to access data associated with files, sockets, pipes, and devices. For files, you can read, write, and seek within the file. For sockets, pipes, and devices, you can use a file handle object to monitor the device and process data asynchronously. Most creation methods for ''FileHandle'' cause the file handle object to take ownership of the associated file descriptor. This means that the file handle object both creates the file descriptor and is responsible for closing it later, usually when the system deallocates the file handle object. If you want to use a file handle object with a file descriptor that you created, use the ''init(fileDescriptor:)'' method or use the ''init(fileDescriptor:closeOnDealloc:)'' method and pass \ for the 'flag' parameter. \#\#\# Run Loop Considerations When using a file handle object to communicate asynchronously with a socket, you must initiate the corresponding operations from a thread with an active run loop. Although the read, accept, and wait operations themselves are performed asynchronously on background threads, the file handle uses a run loop source to monitor the operations and notify your code appropriately. Therefore, you must call those methods from your application's main thread or from any thread where you've configured a run loop and are using it to process events. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -49,207 +48,174 @@ namespace cocoon explicit FileHandle(Adopt adopt); /** * @brief Calls `-[NSFileHandle acceptConnectionInBackgroundAndNotify]`. - * @details Accepts a socket connection (for stream-type sockets only) in the background and creates a file handle for the "near" (client) end of the communications channel. This method asynchronously creates a file handle for the other end of the socket connection and returns that object by posting an 'NSFileHandleConnectionAcceptedNotification'. The notification includes a 'userInfo' dictionary with the created ''FileHandle'' object, accessible using the 'NSFileHandleNotificationFileHandleItem' key. You must call this method from a thread that has an active run loop. */ void accept_connection_in_background_and_notify() const; /** * @brief Calls `-[NSFileHandle acceptConnectionInBackgroundAndNotifyForModes:]`. - * @details Accepts a socket connection (for stream-type sockets only) in the background and creates a file handle for the "near" (client) end of the communications channel. - Parameter modes: The runloop modes in which the connection accepted notification can be posted. See ''FileHandle/acceptConnectionInBackgroundAndNotify()'' for details. This method differs in that the notification is queued for posting in the specified run-loop modes. * @param modes Argument converted to the Objective-C parameter of the same role. */ void accept_connection_in_background_and_notify_for_modes(const std::vector& modes) const; /** * @brief Calls `-[NSFileHandle closeAndReturnError:]`. - * @details Disallows further access to the represented file or communications channel and signals end of file on communications channels that permit writing. If the file handle object owns its file descriptor, it automatically closes that descriptor when it is deallocated. If you initialized the file handle object using the ''FileHandle/init(fileDescriptor:closeOnDealloc:)'' method, the file handle object takes ownership of the file descriptor if you passed 'YES' for the 'flag' parameter. After invoking this method, you may still need to release the file handle object, but the object should not be used to read from or write to the file. * @return The converted Objective-C result. */ bool close_and_return_error() const; /** * @brief Calls `+[NSFileHandle fileHandleForReadingAtPath:]`. - * @details Returns a file handle initialized for reading the file, device, or named socket at the specified path. - Parameter path: The path to the file, device, or named socket to access. - Returns: The initialized file handle object or 'nil' if no file exists at 'path'. The file pointer is set to the beginning of the file. You cannot write data to the returned file handle object. The returned object responds only to ''FileHandle/readData(ofLength:)'', ''FileHandle/readDataToEndOfFile()'', and ''FileHandle/availableData''. The file handle owns its file descriptor. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static FileHandle file_handle_for_reading_at_path(const std::string& path); /** * @brief Calls `+[NSFileHandle fileHandleForReadingFromURL:error:]`. - * @details Returns a file handle initialized for reading the file, device, or named socket at the specified URL. - Parameters: - url: The URL of the file, device, or named socket to access. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. Pass 'NULL' if you do not want error information. - Returns: The initialized file handle object or 'nil' if no file exists at 'url'. The file pointer is set to the beginning of the file. You cannot write data to the returned file handle object. Use the ''FileHandle/readDataToEndOfFile()'' or ''FileHandle/readData(ofLength:)'' methods to read data from it. When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static FileHandle file_handle_for_reading_from_url(const URL& url); /** * @brief Calls `+[NSFileHandle fileHandleForUpdatingAtPath:]`. - * @details Returns a file handle initialized for reading and writing to the file, device, or named socket at the specified path. - Parameter path: The path to the file, device, or named socket to access. - Returns: The initialized file handle object or 'nil' if no file exists at 'path'. The file pointer is set to the beginning of the file. The returned object responds to both read and write messages. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static FileHandle file_handle_for_updating_at_path(const std::string& path); /** * @brief Calls `+[NSFileHandle fileHandleForUpdatingURL:error:]`. - * @details Returns a file handle initialized for reading and writing to the file, device, or named socket at the specified URL. - Parameters: - url: The URL of the file, device, or named socket to access. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. Pass 'NULL' if you do not want error information. - Returns: The initialized file handle object or 'nil' if no file exists at 'url'. The file pointer is set to the beginning of the file. The returned object responds to both read and ''FileHandle/write(:)'' messages. When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static FileHandle file_handle_for_updating_url(const URL& url); /** * @brief Calls `+[NSFileHandle fileHandleForWritingAtPath:]`. - * @details Returns a file handle initialized for writing to the file, device, or named socket at the specified path. - Parameter path: The path to the file, device, or named socket to access. - Returns: The initialized file handle object or 'nil' if no file exists at 'path'. The file pointer is set to the beginning of the file. You cannot read data from the returned file handle object. Use ''FileHandle/write(:)'' to write data to the returned file handle object. The file handle owns its file descriptor. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static FileHandle file_handle_for_writing_at_path(const std::string& path); /** * @brief Calls `+[NSFileHandle fileHandleForWritingToURL:error:]`. - * @details Returns a file handle initialized for writing to the file, device, or named socket at the specified URL. - Parameters: - url: The URL of the file, device, or named socket to access. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. Pass 'NULL' if you do not want error information. - Returns: The initialized file handle object or 'nil' if no file exists at 'url'. The file pointer is set to the beginning of the file. The returned object responds only to ''FileHandle/write(:)''. When using this method to create a file handle object, the file handle owns its associated file descriptor and is responsible for closing it. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static FileHandle file_handle_for_writing_to_url(const URL& url); /** * @brief Calls `-[NSFileHandle getOffset:error:]`. - * @details Gets the position of the file pointer within the file. - Parameters: - offsetInFile: On return, contains the file offset. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. - Returns: 'YES' if the offset was retrieved successfully; otherwise, 'NO'. * @param offset_in_file Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool get_offset(std::uint64_t* offset_in_file) const; /** * @brief Calls `-[NSFileHandle readDataToEndOfFileAndReturnError:]`. - * @details Reads the available data synchronously up to the end of file or maximum number of bytes. - Returns: The data available through the receiver up to the maximum size that can be represented by an 'NSData' object. This method invokes ''FileHandle/readData(ofLength:)'' as part of its implementation. * @return The converted Objective-C result. */ std::vector read_data_to_end_of_file_and_return_error() const; /** * @brief Calls `-[NSFileHandle readDataUpToLength:error:]`. - * @details Reads data synchronously up to the specified number of bytes. - Parameters: - length: The number of bytes to read from the receiver. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. - Returns: The data available through the receiver up to a maximum of 'length' bytes, or 'nil' if an error occurred. If the receiver is a file, this method returns data obtained by reading 'length' bytes starting at the current file pointer. If 'length' bytes are not available, returns as many bytes as are available. Returns an empty 'NSData' when the end of file is reached. * @param length Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector read_data_up_to_length(std::uint64_t length) const; /** * @brief Calls `-[NSFileHandle readInBackgroundAndNotify]`. - * @details Reads from the file or communications channel in the background and posts a notification when finished. This method performs an asynchronous ''FileHandle/availableData'' operation on a file or communications channel and posts an ''FileHandle/readCompletionNotification''. You must call this method from a thread that has an active run loop. */ void read_in_background_and_notify() const; /** * @brief Calls `-[NSFileHandle readInBackgroundAndNotifyForModes:]`. - * @details Reads from the file or communications channel in the background and posts a notification when finished. - Parameter modes: The runloop modes in which the read completion notification can be posted. See ''FileHandle/readInBackgroundAndNotify()'' for details. This method differs in that the notification is queued for posting in the specified run-loop modes. * @param modes Argument converted to the Objective-C parameter of the same role. */ void read_in_background_and_notify_for_modes(const std::vector& modes) const; /** * @brief Calls `-[NSFileHandle readToEndOfFileInBackgroundAndNotify]`. - * @details Reads to the end of file from the file or communications channel in the background and posts a notification when finished. This method performs an asynchronous ''FileHandle/readDataToEndOfFile()'' operation on a file or communications channel and posts an 'NSFileHandleReadToEndOfFileCompletionNotification'. You must call this method from a thread that has an active run loop. */ void read_to_end_of_file_in_background_and_notify() const; /** * @brief Calls `-[NSFileHandle readToEndOfFileInBackgroundAndNotifyForModes:]`. - * @details Reads to the end of file from the file or communications channel in the background and posts a notification when finished. - Parameter modes: The runloop modes in which the read completion notification can be posted. See ''FileHandle/readToEndOfFileInBackgroundAndNotify()'' for details. This method differs in that the notification is queued for posting in the specified run-loop modes. * @param modes Argument converted to the Objective-C parameter of the same role. */ void read_to_end_of_file_in_background_and_notify_for_modes(const std::vector& modes) const; /** * @brief Calls `-[NSFileHandle seekToEndReturningOffset:error:]`. - * @details Places the file pointer at the end of the file and returns the new file offset. - Parameters: - offsetInFile: On return, contains the new file offset, which is the file size. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. - Returns: 'YES' if the operation succeeded; otherwise, 'NO'. * @param offset_in_file Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool seek_to_end_returning_offset(std::uint64_t* offset_in_file) const; /** * @brief Calls `-[NSFileHandle seekToOffset:error:]`. - * @details Moves the file pointer to the specified offset within the file. - Parameters: - offset: The offset to seek to. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. - Returns: 'YES' if the operation succeeded; otherwise, 'NO'. * @param offset Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool seek_to_offset(std::uint64_t offset) const; /** * @brief Calls `-[NSFileHandle synchronizeAndReturnError:]`. - * @details Causes all in-memory data and attributes of the file represented by the file handle to write to permanent storage. This method should be invoked by programs that require the file to be in a known state. Invocation of this method does not return until memory is flushed. * @return The converted Objective-C result. */ bool synchronize_and_return_error() const; /** * @brief Calls `-[NSFileHandle truncateAtOffset:error:]`. - * @details Truncates or extends the file represented by the file handle to a specified offset within the file and puts the file pointer at that position. - Parameters: - offset: The offset within the file that will mark the new end of the file. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. - Returns: 'YES' if the operation succeeded; otherwise, 'NO'. If the file is extended (if 'offset' is beyond the current end of file), the added characters are null bytes. * @param offset Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool truncate_at_offset(std::uint64_t offset) const; /** * @brief Calls `-[NSFileHandle waitForDataInBackgroundAndNotify]`. - * @details Asynchronously checks to see if data is available. When the data becomes available, this method posts a ''FileHandle/dataAvailableNotification'' notification on the current thread. You must call this method from a thread that has an active run loop. */ void wait_for_data_in_background_and_notify() const; /** * @brief Calls `-[NSFileHandle waitForDataInBackgroundAndNotifyForModes:]`. - * @details Asynchronously checks to see if data is available. - Parameter modes: The runloop modes in which the data available notification can be posted. See ''FileHandle/waitForDataInBackgroundAndNotify()'' for details. This method differs in that the notification is queued for posting in the specified run-loop modes. * @param modes Argument converted to the Objective-C parameter of the same role. */ void wait_for_data_in_background_and_notify_for_modes(const std::vector& modes) const; /** * @brief Calls `-[NSFileHandle writeData:error:]`. - * @details Writes the specified data synchronously to the file handle. - Parameters: - data: The data to write. - error: If an error occurs, upon return contains an 'NSError' object that describes the problem. - Returns: 'YES' if the data was written successfully; otherwise, 'NO'. This method writes data at the current file pointer, advancing the file pointer. * @param data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool write_data(const std::vector& data) const; /** * @brief Returns the `availableData` property of `NSFileHandle`. - * @details The data currently available in the receiver. If the receiver is a file, returns the data obtained by reading the file from the current file pointer to the end of the file. If the receiver is a communications channel, reads up to a buffer of data and returns it; if no data is available, the method blocks. Returns an empty data object if the end of file has been reached. Raises ''NSExceptionName/fileHandleOperationException'' upon failure. * @return The converted Objective-C result. */ std::vector available_data() const; /** * @brief Returns the `fileDescriptor` property of `NSFileHandle`. - * @details The POSIX file descriptor associated with the receiver. You can use this property to get the file descriptor while it is open. If the file handle object owns the file descriptor, you must not close it yourself. However, you can use the ''FileHandle/close()'' method to close the file handle, which also closes the file descriptor. If the receiver is not the owner of the file descriptor, closing the file descriptor while the file handle is still associated with it raises ''NSExceptionName/fileHandleOperationException''. * @return The converted Objective-C result. */ int file_descriptor() const; /** * @brief Returns the `fileHandleWithNullDevice` property of `NSFileHandle`. - * @details The file handle associated with a null device. You can use the returned file handle as a "stand in" for standard file handles. Reads from the null-device file handle return an empty ''NSData'' object. Writes to it are discarded. The ''FileHandle/fileDescriptor'' property returns an illegal value. The ''FileHandle/close()'' method has no effect. * @return The converted Objective-C result. */ static FileHandle file_handle_with_null_device(); /** * @brief Returns the `fileHandleWithStandardError` property of `NSFileHandle`. - * @details The file handle associated with the standard error file. Conventionally this is a terminal device to which error messages are sent. There is one standard error file handle per process; it is a shared instance. * @return The converted Objective-C result. */ static FileHandle file_handle_with_standard_error(); /** * @brief Returns the `fileHandleWithStandardInput` property of `NSFileHandle`. - * @details The file handle associated with the standard input file. Conventionally this is a terminal device on which the user enters a stream of data. There is one standard input file handle per process; it is a shared instance. * @return The converted Objective-C result. */ static FileHandle file_handle_with_standard_input(); /** * @brief Returns the `fileHandleWithStandardOutput` property of `NSFileHandle`. - * @details The file handle associated with the standard output file. Conventionally this is a terminal device that receives a stream of data from a program. There is one standard output file handle per process; it is a shared instance. * @return The converted Objective-C result. */ static FileHandle file_handle_with_standard_output(); /** * @brief Returns the `readabilityHandler` property of `NSFileHandle`. - * @details The block to use for reading the contents of the file handle asynchronously. The default value is 'nil'. To read data asynchronously, assign a non-nil block. Doing so creates a dispatch source for the associated file descriptor and submits the block to that source when data arrives. Set to 'nil' to stop reading. * @return The converted Objective-C result. */ std::function readability_handler() const; /** * @brief Sets the `readabilityHandler` property of `NSFileHandle`. - * @details The block to use for reading the contents of the file handle asynchronously. The default value is 'nil'. To read data asynchronously, assign a non-nil block. Doing so creates a dispatch source for the associated file descriptor and submits the block to that source when data arrives. Set to 'nil' to stop reading. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_readability_handler(std::function value) const; /** * @brief Returns the `writeabilityHandler` property of `NSFileHandle`. - * @details The block to use for writing the contents of the file handle asynchronously. The default value is 'nil'. To write data asynchronously, assign a non-nil block. Doing so creates a dispatch source for the associated file descriptor and submits the block when the file handle has room for data. Set to 'nil' to stop. * @return The converted Objective-C result. */ std::function writeability_handler() const; /** * @brief Sets the `writeabilityHandler` property of `NSFileHandle`. - * @details The block to use for writing the contents of the file handle asynchronously. The default value is 'nil'. To write data asynchronously, assign a non-nil block. Doing so creates a dispatch source for the associated file descriptor and submits the block when the file handle has room for data. Set to 'nil' to stop. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_writeability_handler(std::function value) const; diff --git a/include/generated/file_manager.h b/include/generated/file_manager.h index fcf63101..d46961b6 100644 --- a/include/generated/file_manager.h +++ b/include/generated/file_manager.h @@ -18,7 +18,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFileManager` (Foundation). - * @details A convenient interface to the contents of the file system, and the primary means of interacting with it. A file manager object lets you examine the contents of the file system and make changes to it. The ''FileManager'' class provides convenient access to a shared file manager object that is suitable for most types of file-related manipulations. A file manager object is typically your primary mode of interaction with the file system. You use it to locate, create, copy, and move files and directories. You also use it to get information about a file or directory or change some of its attributes. When specifying the location of files, you can use either ''NSURL'' or ''NSString'' objects. The use of the ''NSURL'' class is generally preferred for specifying file-system items because URLs can convert path information to a more efficient representation internally. You can also obtain a bookmark from an ''NSURL'' object, which is similar to an alias and offers a more sure way of locating the file or directory later. If you are moving, copying, linking, or removing files or directories, you can use a delegate in conjunction with a file manager object to manage those operations. The delegate's role is to affirm the operation and to decide whether to proceed when errors occur. In macOS 10.7 and later, the delegate must conform to the ''FileManagerDelegate'' protocol. In iOS 5.0 and later and in macOS 10.7 and later, ''FileManager'' includes methods for managing items stored in iCloud. Files and directories tagged for cloud storage are synced to iCloud so that they can be made available to the user's iOS devices and Macintosh computers. Changes to an item in one location are propagated to all other locations to ensure the items stay in sync. \#\#\# Threading considerations The methods of the shared ''FileManager'' object can be called from multiple threads safely. However, if you use a delegate to receive notifications about the status of move, copy, remove, and link operations, you should create a unique instance of the file manager object, assign your delegate to that object, and use that file manager to initiate your operations. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -51,7 +50,7 @@ namespace cocoon explicit FileManager(Adopt adopt); /** * @brief Calls `-[NSFileManager URLForDirectory:inDomain:appropriateForURL:create:error:]`. - * @details Locates and optionally creates the specified common directory in a domain. - Parameters: - directory: The search path directory. The supported values are described in ''FileManager/SearchPathDirectory''. - domain: The file system domain to search. The value for this parameter is one of the constants described in ''FileManager/SearchPathDomainMask''. You should specify only one domain for your search and you may not specify the ''FileManager/SearchPathDomainMask/allDomainsMask'' constant for this parameter. - url: The file URL used to determine the location of the returned URL. Only the volume of this parameter is used. This parameter is ignored unless the 'directory' parameter contains the value ''FileManager/SearchPathDirectory/itemReplacementDirectory'' and the 'domain' parameter contains the value ''FileManager/SearchPathDomainMask/userDomainMask''. - shouldCreate: Whether to create the directory if it does not already exist. When creating a temporary directory, this parameter is ignored and the directory is always created. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: The ''NSURL'' for the requested directory. When using Objective-C, if an error occurs, this method returns 'nil' and assigns an appropriate error object to the 'error' parameter. You typically use this method to locate one of the standard system directories, such as the 'Documents', 'Application Support' or 'Caches' directories. After locating (or creating) the desired directory, this method returns the URL for that directory. If more than one appropriate directory exists in the specified domain, this method returns only the first one it finds. > Important: > Passing a directory and domain pair that makes no sense (for example ''FileManager/SearchPathDirectory/desktopDirectory'' and ''FileManager/SearchPathDomainMask/networkDomainMask'') raises an exception. You can use this method to create a new temporary directory. To do so, specify ''FileManager/SearchPathDirectory/itemReplacementDirectory'' for the 'directory' parameter, ''FileManager/SearchPathDomainMask/userDomainMask'' for the 'domain' parameter, and a URL for the 'url' parameter which determines the volume of the returned URL. > Important: > If you use this method to create a temporary directory, you should not rely on the existence of that temporary directory after the app is exited. It is recommended that you remove any temporary directories that are created after they're no longer needed. + * @details -URLForDirectory:inDomain:appropriateForURL:create:error: is a URL-based replacement for FSFindFolder(). It allows for the specification and (optional) creation of a specific directory for a particular purpose (e.g. the replacement of a particular item on disk, or a particular Library directory. You may pass only one of the values from the NSSearchPathDomainMask enumeration, and you may not pass NSAllDomainsMask. * @param directory Argument converted to the Objective-C parameter of the same role. * @param domain Argument converted to the Objective-C parameter of the same role. * @param url Argument converted to the Objective-C parameter of the same role. @@ -61,7 +60,7 @@ namespace cocoon URL url_for_directory(SearchPathDirectory directory, SearchPathDomainMask domain, const URL& url, bool should_create) const; /** * @brief Calls `-[NSFileManager URLForPublishingUbiquitousItemAtURL:expirationDate:error:]`. - * @details Returns a URL that can be emailed to users to allow them to download a copy of a flat file item from iCloud. - Parameters: - url: The URL of the item in the cloud that you want to share. The URL must be prefixed with the base URL returned from the 'URLForUbiquityContainerIdentifier:' method that corresponds to the item's location. The file must be a flat file, not a bundle. The file at the specified URL must already be uploaded to iCloud when you call this method. - outDate: On input, a pointer to a variable for a date object. On output, this parameter contains the date after which the item is no longer available at the returned URL. You may specify 'nil' for this parameter if you are not interested in the date. - error: On input, a pointer to variable for an ''NSError'' object. If an error occurs, this pointer is set to an ''NSError'' object containing information about the error. You may specify 'nil' for this parameter if you do not want the error information. - Returns: A URL with which users can download a copy of the item at 'url'. In Objective-C, returns 'nil' if the URL could not be created for any reason. This method creates a snapshot of the specified flat file and places that copy in a temporary iCloud location where it can be accessed by other users using the returned URL. The snapshot reflects the contents of the file at the time the URL was generated and is not updated when subsequent changes are made to the original file in the user's iCloud storage. Your app must have access to the network for this call to succeed. If the specified file is in the process of being uploaded to iCloud, you must not call this method until the upload has finished. > Important: > As of iOS 8.0 and macOS 10.10 The 'url' must specify a flat file, not a bundle. Bundles have a folder as the root item. + * @details Returns a URL that can be shared with other users to allow them download a copy of the specified ubiquitous item. Also returns the date after which the item will no longer be accessible at the returned URL. The URL must be prefixed with a URL from -URLForUbiquityContainerIdentifier:. * @param url Argument converted to the Objective-C parameter of the same role. * @param out_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -69,14 +68,14 @@ namespace cocoon URL url_for_publishing_ubiquitous_item_at_url(const URL& url, Date& out_date) const; /** * @brief Calls `-[NSFileManager URLForUbiquityContainerIdentifier:]`. - * @details Returns the URL for the iCloud container associated with the specified identifier and establishes access to that container. - Parameters: - containerIdentifier: The fully-qualified container identifier for an iCloud container directory. The string you specify must not contain wildcards and must be of the form '\.\', where '\' is your development team ID and '\' is the bundle identifier of the container you want to access. If you specify 'nil' for this parameter, this method returns the first container listed in the 'com.apple.developer.ubiquity-container-identifiers' entitlement array. - Returns: A URL pointing to the specified ubiquity container, or 'nil' if the container could not be located or if iCloud storage is unavailable for the current user or device. You use this method to determine the location of your app's ubiquity container directories and to configure your app's initial iCloud access. The first time you call this method for a given ubiquity container, the system extends your app's sandbox to include that container. > Important: > Do not call this method from your app's main thread. Because this method might take a nontrivial amount of time to set up iCloud and return the requested URL, you should always call it from a secondary thread. To determine if iCloud is available, especially at launch time, check the value of the 'ubiquityIdentityToken' property instead. + * @details Returns a file URL for the root of the ubiquity container directory corresponding to the supplied container ID. Returns nil if the mobile container does not exist or could not be determined. * @param container_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URL url_for_ubiquity_container_identifier(const std::string& container_identifier) const; /** * @brief Calls `-[NSFileManager URLsForDirectory:inDomains:]`. - * @details Returns an array of URLs for the specified common directory in the requested domains. - Parameters: - directory: The search path directory. The supported values are described in ''FileManager/SearchPathDirectory''. - domainMask: The file system domain to search. The value for this parameter is one or more of the constants described in ''FileManager/SearchPathDomainMask''. - Returns: An array of ''NSURL'' objects identifying the requested directories. The directories are ordered according to the order of the domain mask constants, with items in the user domain first and items in the system domain last. This method is intended to locate known and common directories in the system. For example, setting the directory to ''FileManager/SearchPathDirectory/applicationDirectory'', will return the Applications directories in the requested domain. There are a number of common directories available in the ''FileManager/SearchPathDirectory'', including: ''FileManager/SearchPathDirectory/desktopDirectory'', ''FileManager/SearchPathDirectory/applicationSupportDirectory'', and many more. + * @details -URLsForDirectory:inDomains: is analogous to NSSearchPathForDirectoriesInDomains(), but returns an array of NSURL instances for use with URL-taking APIs. This API is suitable when you need to search for a file or files which may live in one of a variety of locations in the domains specified. * @param directory Argument converted to the Objective-C parameter of the same role. * @param domain_mask Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -84,49 +83,48 @@ namespace cocoon std::vector ur_ls_for_directory(SearchPathDirectory directory, SearchPathDomainMask domain_mask) const; /** * @brief Calls `-[NSFileManager attributesOfFileSystemForPath:error:]`. - * @details Returns a dictionary that describes the attributes of the mounted file system on which a given path resides. - Parameters: - path: Any pathname within the mounted file system. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: A dictionary object that describes the attributes of the mounted file system on which 'path' resides. See 'File-System Attribute Keys' for a description of the keys available in the dictionary. This method does not traverse a terminal symbolic link. + * @details attributesOfFileSystemForPath:error: returns an NSDictionary of key/value pairs containing the attributes of the filesystem containing the provided path. If this method returns 'nil', an NSError will be returned by reference in the 'error' parameter. This method does not traverse a terminal symlink. This method replaces fileSystemAttributesAtPath:. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map attributes_of_file_system_for_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager attributesOfItemAtPath:error:]`. - * @details Returns the attributes of the item at a given path. - Parameters: - path: The path of a file or directory. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: A dictionary object that describes the attributes (file, directory, symlink, and so on) of the file specified by 'path' (or 'nil' if an error occurred in Objective-C). The keys in the dictionary are described in 'File Attribute Keys'. If the item at the path is a symbolic link---that is, the value of the 'NSFileType' key in the attributes dictionary is 'NSFileTypeSymbolicLink'---you can use the ''FileManager/destinationOfSymbolicLink(atPath:)'' method to retrieve the path of the item pointed to by the link. You can also use the 'stringByResolvingSymlinksInPath' method of ''NSString'' to resolve links in the path before retrieving the item's attributes. As a convenience, ''NSDictionary'' provides a set of methods (declared as a category on ''NSDictionary'') for quickly and efficiently obtaining attribute information from the returned dictionary: 'fileGroupOwnerAccountName', 'fileModificationDate', 'fileOwnerAccountName', 'filePosixPermissions', 'fileSize', 'fileSystemFileNumber', 'fileSystemNumber', and 'fileType'. + * @details attributesOfItemAtPath:error: returns an NSDictionary of key/value pairs containing the attributes of the item (file, directory, symlink, etc.) at the path in question. If this method returns 'nil', an NSError will be returned by reference in the 'error' parameter. This method does not traverse a terminal symlink. This method replaces fileAttributesAtPath:traverseLink:. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map attributes_of_item_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager changeCurrentDirectoryPath:]`. - * @details Changes the path of the current working directory to the specified path. - Parameters: - path: The path of the directory to which to change. - Returns: 'YES' if successful, otherwise 'NO'. All relative pathnames refer implicitly to the current working directory. > Warning: > This method changes the current working directory for the current process, not just the receiver. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool change_current_directory_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager componentsToDisplayForPath:]`. - * @details Returns an array of strings representing the user-visible components of a given path. - Parameters: - path: A pathname. - Returns: An array of ''NSString'' objects representing the user-visible (for the Finder, Open and Save panels, and so on) components of 'path'. Returns 'nil' if path does not exist. These components cannot be used for path operations and are only suitable for display to the user. + * @details componentsToDisplayForPath: returns an NSArray of display names for the path provided. Localization will occur as in displayNameAtPath: above. This array cannot and should not be reassembled into an usable filesystem path for any kind of access. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector components_to_display_for_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager containerURLForSecurityApplicationGroupIdentifier:]`. - * @details Returns the container directory associated with the specified security application group identifier. - Parameters: - groupIdentifier: A string that names the group whose shared directory you want to obtain. This input should exactly match one of the strings in the app's App Groups entitlement. - Returns: A URL indicating the location of the group's shared directory in the file system. In iOS, the value is 'nil' when the group identifier is invalid. In macOS, a URL of the expected form is always returned, even if the app group is invalid, so be sure to test that you can access the underlying directory before attempting to use it. Sandboxed apps in macOS and all apps in iOS that need to share files with other apps from the same developer on a given device use the App Groups entitlement to join one or more application groups. + * @details Returns the container directory associated with the specified security application group ID. * @param group_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URL container_url_for_security_application_group_identifier(const std::string& group_identifier) const; /** * @brief Calls `-[NSFileManager contentsAtPath:]`. - * @details Returns the contents of the file at the specified path. - Parameters: - path: The path of the file whose contents you want. - Returns: An ''NSData'' object with the contents of the file. If 'path' specifies a directory, or if some other error occurs, this method returns 'nil'. + * @details These methods are provided here for compatibility. The corresponding methods on NSData which return NSErrors should be regarded as the primary method of creating a file from an NSData or retrieving the contents of a file as an NSData. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector contents_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager contentsEqualAtPath:andPath:]`. - * @details Returns a Boolean value that indicates whether the files or directories in specified paths have the same contents. - Parameters: - path1: The path of a file or directory to compare with the contents of 'path2'. - path2: The path of a file or directory to compare with the contents of 'path1'. - Returns: 'YES' if file or directory specified in 'path1' has the same contents as that specified in 'path2', otherwise 'NO'. If 'path1' and 'path2' are directories, the contents are the list of files and subdirectories each contains---contents of subdirectories are also compared. For files, this method checks to see if they're the same file, then compares their size, and finally compares their contents. This method does not traverse symbolic links, but compares the links themselves. + * @details -contentsEqualAtPath:andPath: does not take into account data stored in the resource fork or filesystem extended attributes. * @param path1 Argument converted to the Objective-C parameter of the same role. * @param path2 Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -134,14 +132,14 @@ namespace cocoon bool contents_equal_at_path(const std::string& path1, const std::string& path2) const; /** * @brief Calls `-[NSFileManager contentsOfDirectoryAtPath:error:]`. - * @details Performs a shallow search of the specified directory and returns the paths of any contained items. - Parameters: - path: The path to the directory whose contents you want to enumerate. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: An array of ''NSString'' objects, each of which identifies a file, directory, or symbolic link contained in 'path'. Returns an empty array if the directory exists but has no contents. In Objective-C, if an error occurs, this method returns 'nil' and assigns an appropriate error object to the 'error' parameter. This method performs a shallow search of the directory and therefore does not traverse symbolic links or return the contents of any subdirectories. This method also does not return URLs for the current directory ("'.'"), parent directory ("'..'"), or resource forks (files that begin with "'.'") but it does return other hidden files (files that begin with a period character). If you need to perform a deep enumeration, use the ''NSFileManager/enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:'' method instead. The order of the files in the returned array is undefined. + * @details contentsOfDirectoryAtPath:error: returns an NSArray of NSStrings representing the filenames of the items in the directory. If this method returns 'nil', an NSError will be returned by reference in the 'error' parameter. If the directory contains no items, this method will return the empty array. This method replaces directoryContentsAtPath: * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector contents_of_directory_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error:]`. - * @details Performs a shallow search of the specified directory and returns URLs for the contained items. - Parameters: - url: The URL for the directory whose contents you want to enumerate. - keys: An array of keys that identify the file properties that you want pre-fetched for each item in the directory. For each returned URL, the specified properties are fetched and cached in the ''NSURL'' object. For a list of keys you can specify, see Common File System Resource Keys. If you want directory contents to have no pre-fetched file properties, pass an empty array to this parameter. If you want directory contents to have default set of pre-fetched file properties, pass 'nil' to this parameter. - mask: Options for the enumeration. Because this method performs only shallow enumerations, options that prevent descending into subdirectories or packages are not allowed; the only supported option is ''FileManager/DirectoryEnumerationOptions/skipsHiddenFiles''. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: An array of ''NSURL'' objects, each of which identifies a file, directory, or symbolic link contained in 'url'. If the directory contains no entries, this method returns an empty array. When using Objective-C, if an error occurs, this method returns 'nil' and assigns an appropriate error object to the 'error' parameter. This method performs a shallow search of the directory and therefore does not traverse symbolic links or return the contents of any subdirectories. This method also does not return URLs for the current directory ("'.'"), parent directory ("'..'"), or resource forks (files that begin with "'.'") but it does return other hidden files. If you need to perform a deep enumeration, use the ''NSFileManager/enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:'' method instead. The order of the files in the returned array is undefined. + * @details -contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error: returns an NSArray of NSURLs identifying the the directory entries. If this method returns nil, an NSError will be returned by reference in the 'error' parameter. If the directory contains no entries, this method will return the empty array. When an array is specified for the 'keys' parameter, the specified property values will be pre-fetched and cached with each enumerated URL. This method always does a shallow enumeration of the specified directory (i.e. it always acts as if NSDirectoryEnumerationSkipsSubdirectoryDescendants has been specified). If you need to perform a deep enumeration, use -[NSFileManager enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:]. If you wish to only receive the URLs and no other attributes, then pass '0' for 'options' and an empty NSArray ('[NSArray array]') for 'keys'. If you wish to have the property caches of the vended URLs pre-populated with a default set of attributes, then pass '0' for 'options' and 'nil' for 'keys'. * @param url Argument converted to the Objective-C parameter of the same role. * @param keys Argument converted to the Objective-C parameter of the same role. * @param mask Argument converted to the Objective-C parameter of the same role. @@ -150,7 +148,7 @@ namespace cocoon std::vector contents_of_directory_at_url(const URL& url, const std::vector& keys, DirectoryEnumerationOptions mask) const; /** * @brief Calls `-[NSFileManager copyItemAtPath:toPath:error:]`. - * @details Copies the item at the specified path to a new location synchronously. - Parameters: - srcPath: The path to the file or directory you want to copy. This parameter must not be 'nil'. - dstPath: The path at which to place the copy of 'srcPath'. This path must include the name of the file or directory in its new location. This parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the item was copied successfully or the file manager's delegate stopped the operation deliberately. Returns 'NO' if an error occurred. When copying items, the current process must have permission to read the file or directory at 'srcPath' and write the parent directory of 'dstPath'. If the item at 'srcPath' is a directory, this method copies the directory and all of its contents, including any hidden files. If a file with the same name already exists at 'dstPath', this method stops the copy attempt and returns an appropriate error. If the last component of 'srcPath' is a symbolic link, only the link is copied to the new path. Prior to copying an item, the file manager asks its delegate if it should actually do so for each item. It does this by calling the 'fileManager:shouldCopyItemAtURL:toURL:' method; if that method is not implemented it calls the 'fileManager:shouldCopyItemAtPath:toPath:' method instead. If the delegate method returns 'YES', or if the delegate does not implement the appropriate methods, the file manager copies the given file or directory. If there is an error copying an item, the file manager may also call the delegate's 'fileManager:shouldProceedAfterError:copyingItemAtURL:toURL:' or 'fileManager:shouldProceedAfterError:copyingItemAtPath:toPath:' method to determine how to proceed. + * @details These methods replace their non-error returning counterparts below. See the NSFileManagerDelegate protocol below for methods that are dispatched to the NSFileManager instance's delegate. * @param src_path Argument converted to the Objective-C parameter of the same role. * @param dst_path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -158,7 +156,7 @@ namespace cocoon bool copy_item_at_path(const std::string& src_path, const std::string& dst_path) const; /** * @brief Calls `-[NSFileManager copyItemAtURL:toURL:error:]`. - * @details Copies the file at the specified URL to a new location synchronously. - Parameters: - srcURL: The file URL that identifies the file you want to copy. The URL in this parameter must not be a file reference URL. This parameter must not be 'nil'. - dstURL: The URL at which to place the copy of 'srcURL'. The URL in this parameter must not be a file reference URL and must include the name of the file in its new location. This parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the item was copied successfully or the file manager's delegate stopped the operation deliberately. Returns 'NO' if an error occurred. When copying items, the current process must have permission to read the file or directory at 'srcURL' and write the parent directory of 'dstURL'. If the item at 'srcURL' is a directory, this method copies the directory and all of its contents, including any hidden files. If a file with the same name already exists at 'dstURL', this method stops the copy attempt and returns an appropriate error. If the last component of 'srcURL' is a symbolic link, only the link is copied to the new path. + * @details These methods are URL-taking equivalents of the four methods above. Their delegate methods are defined in the NSFileManagerDelegate protocol below. * @param src_url Argument converted to the Objective-C parameter of the same role. * @param dst_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -166,7 +164,7 @@ namespace cocoon bool copy_item_at_url(const URL& src_url, const URL& dst_url) const; /** * @brief Calls `-[NSFileManager createDirectoryAtPath:withIntermediateDirectories:attributes:error:]`. - * @details Creates a directory with given attributes at the specified path. - Parameters: - path: A path string identifying the directory to create. You may specify a full path or a path that is relative to the current working directory. This parameter must not be 'nil'. - createIntermediates: If 'YES', this method creates any nonexistent parent directories as part of creating the directory in 'path'. If 'NO', this method fails if any of the intermediate parent directories does not exist. This method also fails if any of the intermediate path elements corresponds to a file and not a directory. - attributes: The file attributes for the new directory and any newly created intermediate directories. You can set the owner and group numbers, file permissions, and modification date. If you specify 'nil' for this parameter or omit a particular value, one or more default values are used as described in the discussion. Some of the keys, such as 'NSFileHFSCreatorCode' and 'NSFileHFSTypeCode', do not apply to directories. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the directory was created, 'YES' if 'createIntermediates' is set and the directory already exists, or 'NO' if an error occurred. If you specify 'nil' for the 'attributes' parameter, this method uses a default set of values for the owner, group, and permissions of any newly created directories in the path. Similarly, if you omit a specific attribute, the default value is used. The default values for newly created directories are as follows: - Permissions are set according to the umask of the current process. For more information, see umask. - The owner ID is set to the effective user ID of the process. - The group ID is set to that of the parent directory. + * @details createDirectoryAtPath:withIntermediateDirectories:attributes:error: creates a directory at the specified path. If you pass 'NO' for createIntermediates, the directory must not exist at the time this call is made. Passing 'YES' for 'createIntermediates' will create any necessary intermediate directories. This method returns YES if all directories specified in 'path' were created and attributes were set. Directories are created with attributes specified by the dictionary passed to 'attributes'. If no dictionary is supplied, directories are created according to the umask of the process. This method returns NO if a failure occurs at any stage of the operation. If an error parameter was provided, a presentable NSError will be returned by reference. This method replaces createDirectoryAtPath:attributes: * @param path Argument converted to the Objective-C parameter of the same role. * @param create_intermediates Argument converted to the Objective-C parameter of the same role. * @param attributes Argument converted to the Objective-C parameter of the same role. @@ -175,7 +173,7 @@ namespace cocoon bool create_directory_at_path(const std::string& path, bool create_intermediates, const std::map& attributes) const; /** * @brief Calls `-[NSFileManager createDirectoryAtURL:withIntermediateDirectories:attributes:error:]`. - * @details Creates a directory with the given attributes at the specified URL. - Parameters: - url: A file URL that specifies the directory to create. If you want to specify a relative path, you must set the current working directory before creating the corresponding ''NSURL'' object. This parameter must not be 'nil'. - createIntermediates: If 'YES', this method creates any nonexistent parent directories as part of creating the directory in 'url'. If 'NO', this method fails if any of the intermediate parent directories does not exist. - attributes: The file attributes for the new directory. You can set the owner and group numbers, file permissions, and modification date. If you specify 'nil' for this parameter, the directory is created according to the umask(2) of the process. Some of the keys, such as 'NSFileHFSCreatorCode' and 'NSFileHFSTypeCode', do not apply to directories. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the directory was created, 'YES' if 'createIntermediates' is set and the directory already exists, or 'NO' if an error occurred. If you specify 'nil' for the 'attributes' parameter, this method uses a default set of values for the owner, group, and permissions of any newly created directories in the path. Similarly, if you omit a specific attribute, the default value is used. The default values for newly created directories are as follows: - Permissions are set according to the umask of the current process. For more information, see umask. - The owner ID is set to the effective user ID of the process. - The group ID is set to that of the parent directory. If you want to specify a relative path for url, you must set the current working directory before creating the corresponding ''NSURL'' object. + * @details createDirectoryAtURL:withIntermediateDirectories:attributes:error: creates a directory at the specified URL. If you pass 'NO' for withIntermediateDirectories, the directory must not exist at the time this call is made. Passing 'YES' for withIntermediateDirectories will create any necessary intermediate directories. This method returns YES if all directories specified in 'url' were created and attributes were set. Directories are created with attributes specified by the dictionary passed to 'attributes'. If no dictionary is supplied, directories are created according to the umask of the process. This method returns NO if a failure occurs at any stage of the operation. If an error parameter was provided, a presentable NSError will be returned by reference. * @param url Argument converted to the Objective-C parameter of the same role. * @param create_intermediates Argument converted to the Objective-C parameter of the same role. * @param attributes Argument converted to the Objective-C parameter of the same role. @@ -184,7 +182,6 @@ namespace cocoon bool create_directory_at_url(const URL& url, bool create_intermediates, const std::map& attributes) const; /** * @brief Calls `-[NSFileManager createFileAtPath:contents:attributes:]`. - * @details Creates a file with the specified content and attributes at the given location. - Parameters: - path: The path for the new file. - data: A data object containing the contents of the new file. - attr: A dictionary containing the attributes to associate with the new file. You can use these attributes to set the owner and group numbers, file permissions, and modification date. For a list of keys, see 'NSFileAttributeKey'. If you specify 'nil' for 'attributes', the file is created with a set of default attributes. - Returns: 'YES' if the operation was successful or if the item already exists, otherwise 'NO'. If you specify 'nil' for the 'attributes' parameter, this method uses a default set of values for the owner, group, and permissions of any newly created directories in the path. Similarly, if you omit a specific attribute, the default value is used. The default values for newly created files are as follows: - Permissions are set according to the umask of the current process. For more information, see umask. - The owner ID is set to the effective user ID of the process. - The group ID is set to that of the parent directory. If a file already exists at 'path', this method overwrites the contents of that file if the current process has the appropriate privileges to do so. * @param path Argument converted to the Objective-C parameter of the same role. * @param data Argument converted to the Objective-C parameter of the same role. * @param attr Argument converted to the Objective-C parameter of the same role. @@ -193,7 +190,7 @@ namespace cocoon bool create_file_at_path(const std::string& path, const std::vector& data, const std::map& attr) const; /** * @brief Calls `-[NSFileManager createSymbolicLinkAtPath:withDestinationPath:error:]`. - * @details Creates a symbolic link that points to the specified destination. - Parameters: - path: The path at which to create the new symbolic link. The last path component is used as the name of the link. - destPath: The path that contains the item to be pointed to by the link. In other words, this is the destination of the link. - error: If an error occurs, upon return contains an ''NSError'' object that describes the problem. Pass 'NULL' if you do not want error information. - Returns: 'YES' if the symbolic link was created or 'NO' if an error occurred. This method also returns 'NO' if a file, directory, or link already exists at 'path'. This method does not traverse symbolic links contained in 'destPath', making it possible to create symbolic links to locations that do not yet exist. Also, if the final path component in 'path' is a symbolic link, that link is not followed. + * @details createSymbolicLinkAtPath:withDestination:error: returns YES if the symbolic link that point at 'destPath' was able to be created at the location specified by 'path'. If this method returns NO, the link was unable to be created and an NSError will be returned by reference in the 'error' parameter. This method does not traverse a terminal symlink. This method replaces createSymbolicLinkAtPath:pathContent: * @param path Argument converted to the Objective-C parameter of the same role. * @param dest_path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -201,7 +198,7 @@ namespace cocoon bool create_symbolic_link_at_path(const std::string& path, const std::string& dest_path) const; /** * @brief Calls `-[NSFileManager createSymbolicLinkAtURL:withDestinationURL:error:]`. - * @details Creates a symbolic link at the specified URL that points to an item at the given URL. - Parameters: - url: The file URL at which to create the new symbolic link. The last path component of the URL issued as the name of the link. - destURL: The file URL that contains the item to be pointed to by the link. In other words, this is the destination of the link. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the symbolic link was created or 'NO' if an error occurred. This method also returns 'NO' if a file, directory, or link already exists at 'url'. This method does not traverse symbolic links contained in 'destURL', making it possible to create symbolic links to locations that do not yet exist. Also, if the final path component in 'url' is a symbolic link, that link is not followed. + * @details createSymbolicLinkAtURL:withDestinationURL:error: returns YES if the symbolic link that point at 'destURL' was able to be created at the location specified by 'url'. 'destURL' is always resolved against its base URL, if it has one. If 'destURL' has no base URL and it's 'relativePath' is indeed a relative path, then a relative symlink will be created. If this method returns NO, the link was unable to be created and an NSError will be returned by reference in the 'error' parameter. This method does not traverse a terminal symlink. * @param url Argument converted to the Objective-C parameter of the same role. * @param dest_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -209,28 +206,28 @@ namespace cocoon bool create_symbolic_link_at_url(const URL& url, const URL& dest_url) const; /** * @brief Calls `-[NSFileManager destinationOfSymbolicLinkAtPath:error:]`. - * @details Returns the path of the item pointed to by a symbolic link. - Parameters: - path: The path of a file or directory. - error: If an error occurs, upon return contains an ''NSError'' object that describes the problem. Pass 'NULL' if you do not want error information. - Returns: An ''NSString'' object containing the path of the directory or file to which the symbolic link 'path' refers. When using Objective-C, returns 'nil' upon failure. If the symbolic link is specified as a relative path, that relative path is returned. + * @details destinationOfSymbolicLinkAtPath:error: returns an NSString containing the path of the item pointed at by the symlink specified by 'path'. If this method returns 'nil', an NSError will be returned by reference in the 'error' parameter. This method replaces pathContentOfSymbolicLinkAtPath: * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string destination_of_symbolic_link_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager displayNameAtPath:]`. - * @details Returns the display name of the file or directory at a specified path. - Parameters: - path: The path of a file or directory. - Returns: The name of the file or directory at 'path' in a localized form appropriate for presentation to the user. If there is no file or directory at 'path', or if an error occurs, returns 'path' as is. Display names are user-friendly names for files. They are typically used to localize standard file and directory names according to the user's language settings. They may also reflect other modifications, such as the removal of filename extensions. Such modifications are used only when displaying the file or directory to the user and do not reflect the actual path to the item in the file system. + * @details displayNameAtPath: returns an NSString suitable for presentation to the user. For directories which have localization information, this will return the appropriate localized string. This string is not suitable for passing to anything that must interact with the filesystem. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string display_name_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager enumeratorAtPath:]`. - * @details Returns a directory enumerator object that can be used to perform a deep enumeration of the directory at the specified path. - Parameters: - path: The path of the directory to enumerate. - Returns: A ''FileManager/DirectoryEnumerator'' object that enumerates the contents of the directory at 'path'. If 'path' is a filename, the method returns an enumerator object that enumerates no files---the first call to 'nextObject' will return 'nil'. Because the enumeration is deep---that is, it lists the contents of all subdirectories---this enumerator object is useful for performing actions that involve large file-system subtrees. This method does not resolve symbolic links encountered in the traversal process, nor does it recurse through them if they point to a directory. The ''FileManager/DirectoryEnumerator'' class has methods for obtaining the attributes of the existing path and of the parent directory and for skipping descendants of the existing path. + * @details enumeratorAtPath: returns an NSDirectoryEnumerator rooted at the provided path. If the enumerator cannot be created, this returns NULL. Because NSDirectoryEnumerator is a subclass of NSEnumerator, the returned object can be used in the for...in construct. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DirectoryEnumeratorBase enumerator_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:]`. - * @details Returns a directory enumerator object that can be used to perform a deep enumeration of the directory at the specified URL. - Parameters: - url: The location of the directory for which you want an enumeration. This URL must not be a symbolic link that points to the desired directory. You can use the 'resolvingSymlinksInPath' method to resolve any symlinks in the URL. - keys: An array of keys that identify the properties that you want pre-fetched for each item in the enumeration. The values for these keys are cached in the corresponding ''NSURL'' objects. You may specify 'nil' for this parameter. For a list of keys you can specify, see ''URLResourceKey''. - mask: Options for the enumeration. For a list of valid options, see 'NSDirectoryEnumerationOptions'. - handler: An optional error handler block for the file manager to call when an error occurs. The handler block should return 'YES' if you want the enumeration to continue or 'NO' if you want the enumeration to stop. If you specify 'nil' for this parameter, the enumerator object continues to enumerate items as if you had specified a block that returned 'YES'. - Returns: A directory enumerator object that enumerates the contents of the directory at 'url'. If 'url' is a filename, the method returns an enumerator object that enumerates no files---the first call to 'nextObject' returns 'nil'. Because the enumeration is deep---that is, it lists the contents of all subdirectories---this enumerator object is useful for performing actions that involve large file-system subtrees. If the method is passed a directory on which another file system is mounted (a mount point), it traverses the mount point. This method does not resolve symbolic links or mount points encountered in the enumeration process, nor does it recurse through them if they point to a directory. The ''FileManager/DirectoryEnumerator'' class has methods for skipping descendants of the existing path and for returning the number of levels deep the current object is in the directory hierarchy being enumerated (where the directory passed to this method is considered to be level 0). + * @details enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: returns an NSDirectoryEnumerator rooted at the provided directory URL. The NSDirectoryEnumerator returns NSURLs from the -nextObject method. The optional 'includingPropertiesForKeys' parameter indicates which resource properties should be pre-fetched and cached with each enumerated URL. The optional 'errorHandler' block argument is invoked when an error occurs. Parameters to the block are the URL on which an error occurred and the error. When the error handler returns YES, enumeration continues if possible. Enumeration stops immediately when the error handler returns NO. If you wish to only receive the URLs and no other attributes, then pass '0' for 'options' and an empty NSArray ('[NSArray array]') for 'keys'. If you wish to have the property caches of the vended URLs pre-populated with a default set of attributes, then pass '0' for 'options' and 'nil' for 'keys'. * @param url Argument converted to the Objective-C parameter of the same role. * @param keys Argument converted to the Objective-C parameter of the same role. * @param mask Argument converted to the Objective-C parameter of the same role. @@ -240,7 +237,7 @@ namespace cocoon DirectoryEnumeratorBase enumerator_at_url(const URL& url, const std::vector& keys, DirectoryEnumerationOptions mask, std::function handler) const; /** * @brief Calls `-[NSFileManager evictUbiquitousItemAtURL:error:]`. - * @details Removes the local copy of the specified item that's stored in iCloud. - Parameters: - url: The URL to a file or directory in iCloud storage. - error: On input, a pointer to variable for an ''NSError'' object. If an error occurs, this pointer is set to an ''NSError'' object containing information about the error. You may specify 'nil' to ignore the error information. - Returns: 'YES' if the local item was removed successfully or 'NO' if it was not. Don't use a coordinated write to perform this operation. This method doesn't remove the item from iCloud. It removes only the local version. You can then use 'startDownloadingUbiquitousItemAtURL:error:' to force iCloud to download a new version of the file or directory from the server. To delete a file permanently from the user's iCloud storage, use the regular ''NSFileManager'' routines for deleting files and directories. Remember that deleting items from iCloud can't be undone. Once deleted, the item is gone forever. + * @details Removes the local instance of the ubiquitous item at the given URL. Returns YES if removal was successful, NO otherwise. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -254,14 +251,13 @@ namespace cocoon void fetch_latest_remote_version_of_item_at_url(const URL& url, std::function completion_handler) const; /** * @brief Calls `-[NSFileManager fileExistsAtPath:]`. - * @details Returns a Boolean value that indicates whether a file or directory exists at a specified path. - Parameters: - path: The path of the file or directory. If 'path' begins with a tilde ('~'), it must first be expanded with 'stringByExpandingTildeInPath'; otherwise, this method returns 'NO'. - Returns: 'YES' if a file at the specified path exists, or 'NO' if the file does not exist or its existence could not be determined. If the file at 'path' is inaccessible to your app, perhaps because one or more parent directories are inaccessible, this method returns 'NO'. If the final element in 'path' specifies a symbolic link, this method traverses the link and returns 'YES' or 'NO' based on the existence of the file at the link destination. > Note: > Attempting to predicate behavior based on the current state of the file system or a particular file on the file system is not recommended. Doing so can cause odd behavior or race conditions. It's far better to attempt an operation (such as loading a file or creating a directory), check for errors, and handle those errors gracefully than it is to try to figure out ahead of time whether the operation will succeed. + * @details The following methods are of limited utility. Attempting to predicate behavior based on the current state of the filesystem or a particular file on the filesystem is encouraging odd behavior in the face of filesystem race conditions. It's far better to attempt an operation (like loading a file or creating a directory) and handle the error gracefully than it is to try to figure out ahead of time whether the operation will succeed. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool file_exists_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager fileExistsAtPath:isDirectory:]`. - * @details Returns a Boolean value that indicates whether a file or directory exists at a specified path. - Parameters: - path: The path of a file or directory. If 'path' begins with a tilde ('~'), it must first be expanded with 'stringByExpandingTildeInPath', or this method will return 'NO'. - isDirectory: Upon return, contains 'YES' if 'path' is a directory or if the final path element is a symbolic link that points to a directory; otherwise, contains 'NO'. If 'path' doesn't exist, this value is undefined upon return. Pass 'NULL' if you do not need this information. - Returns: 'YES' if a file at the specified path exists, or 'NO' if the file's does not exist or its existence could not be determined. If the file at 'path' is inaccessible to your app, perhaps because one or more parent directories are inaccessible, this method returns 'NO'. If the final element in 'path' specifies a symbolic link, this method traverses the link and returns 'YES' or 'NO' based on the existence of the file at the link destination. > Note: > Attempting to predicate behavior based on the current state of the file system or a particular file on the file system is not recommended. Doing so can cause odd behavior or race conditions. It's far better to attempt an operation (such as loading a file or creating a directory), check for errors, and handle those errors gracefully than it is to try to figure out ahead of time whether the operation will succeed. * @param path Argument converted to the Objective-C parameter of the same role. * @param is_directory Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -269,21 +265,21 @@ namespace cocoon bool file_exists_at_path(const std::string& path, bool* is_directory) const; /** * @brief Calls `-[NSFileManager fileSystemRepresentationWithPath:]`. - * @details Returns a C-string representation of a given path that properly encodes Unicode strings for use by the file system. - Parameters: - path: A string object containing a path to a file. This parameter must not be 'nil' or contain the empty string. - Returns: A C-string representation of 'path' that properly encodes Unicode strings for use by the file system. Use this method if your code calls system routines that expect C-string path arguments. If you use the C string beyond the scope of the current autorelease pool, you must copy it. This method raises an exception if 'path' is 'nil' or contains the empty string. This method also throws an exception if the conversion of the string fails. + * @details fileSystemRepresentationWithPath: returns an array of characters suitable for passing to lower-level POSIX style APIs. The string is provided in the representation most appropriate for the filesystem in question. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string file_system_representation_with_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager getFileProviderServicesForItemAtURL:completionHandler:]`. - * @details Returns the services provided by the File Provider extension that manages the item at the given URL. - Parameters: - url: The file URL of a document or directory. - completionHandler: A block that is called on an anonymous background queue. The system passes this block the following parameters: 'services' (if the request is successful, a dictionary with zero or more 'NSFileProviderServiceName' keys and their corresponding 'NSFileProviderService' values; otherwise, 'nil') and 'error' (if an error occurs, an object that describes the error; otherwise, 'nil'). Use the returned services to perform custom actions defined by the services' protocol. To access a service, get the 'NSFileProviderService' object for the desired service name, get an 'NSXPCConnection' from it, set up its 'remoteObjectInterface' with the protocol that matches the service's name, call 'resume' on the connection, and then call custom action methods on the proxy object. + * @details Asynchronously returns a dictionary of zero or more NSFileProviderService instances, which enable your application to instruct the file's provider to take various actions on or with regards to the given URL. To do this, first identify an NSFileProviderService object whose name matches the service you wish to use. Then get an NSXPCConnection from it and set up its NSXPCInterface with the protocol that matches the service's name. You'll need to refer to external documentation or an SDK supplied by the provider to get this information. Once an NSXPCConnection is obtained, you must finish configuring it and send it -resume. Failure to do so will result in leaking system resources. * @param url Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void get_file_provider_services_for_item_at_url(const URL& url, std::function, Error)> completion_handler) const; /** * @brief Calls `-[NSFileManager getRelationship:ofDirectory:inDomain:toItemAtURL:error:]`. - * @details Determines the type of relationship that exists between a system directory and the specified item. - Parameters: - outRelationship: A pointer to a variable in which to put the relationship between 'directoryURL' and 'otherURL'. For a list of possible values, see ''FileManager/URLRelationship''. - directory: The search path directory. For a list of possible values, see ''FileManager/SearchPathDirectory''. - domainMask: The file system domain to search. Specify '0' for this parameter if you want the file manager to choose the domain appropriate for 'url'. - url: The URL of the file or directory whose relationship to 'directoryURL' is being tested. This parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the relationship between the items was successfully determined, or 'NO' if an error occurred. Use this method to determine the relationship between an item and one of the system-specific directories. For example, you might use this method to determine if the specified item is in the user's 'Documents' directory or is in the trash. If the relationship between the items is determined successfully, this method sets the value of the 'outRelationship' parameter to an appropriate value. The directory may contain the item, it may be the same as the item, or it may not have a direct relationship to the item. + * @details Similar to -[NSFileManager getRelationship:ofDirectoryAtURL:toItemAtURL:error:], except that the directory is instead defined by an NSSearchPathDirectory and NSSearchPathDomainMask. Pass 0 for domainMask to instruct the method to automatically choose the domain appropriate for 'url'. For example, to discover if a file is contained by a Trash directory, call [fileManager getRelationship:&result ofDirectory:NSTrashDirectory inDomain:0 toItemAtURL:url error:&error]. * @param out_relationship Argument converted to the Objective-C parameter of the same role. * @param directory Argument converted to the Objective-C parameter of the same role. * @param domain_mask Argument converted to the Objective-C parameter of the same role. @@ -293,7 +289,7 @@ namespace cocoon bool get_relationship(URLRelationship* out_relationship, SearchPathDirectory directory, SearchPathDomainMask domain_mask, const URL& url) const; /** * @brief Calls `-[NSFileManager getRelationship:ofDirectoryAtURL:toItemAtURL:error:]`. - * @details Determines the type of relationship that exists between a directory and an item. - Parameters: - outRelationship: A pointer to a variable in which to put the relationship between 'directoryURL' and 'otherURL'. For a list of possible values, see ''FileManager/URLRelationship''. - directoryURL: The URL of the directory that potentially contains the item in 'otherURL'. The URL in this parameter must specify a directory. This parameter must not be 'nil'. - otherURL: The URL of the file or directory whose relationship to 'directoryURL' is being tested. This parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the relationship between the items was successfully determined, or 'NO' if an error occurred. Use this method to determine the relationship between an item and a directory whose location you already know. If the relationship between the items is determined successfully, this method sets the value of the 'outRelationship' parameter to an appropriate value. The directory may contain the item, it may be the same as the item, or it may not have a direct relationship to the item. + * @details Sets 'outRelationship' to NSURLRelationshipContains if the directory at 'directoryURL' directly or indirectly contains the item at 'otherURL', meaning 'directoryURL' is found while enumerating parent URLs starting from 'otherURL'. Sets 'outRelationship' to NSURLRelationshipSame if 'directoryURL' and 'otherURL' locate the same item, meaning they have the same NSURLFileResourceIdentifierKey value. If 'directoryURL' is not a directory, or does not contain 'otherURL' and they do not locate the same file, then sets 'outRelationship' to NSURLRelationshipOther. If an error occurs, returns NO and sets 'error'. * @param out_relationship Argument converted to the Objective-C parameter of the same role. * @param directory_url Argument converted to the Objective-C parameter of the same role. * @param other_url Argument converted to the Objective-C parameter of the same role. @@ -302,49 +298,43 @@ namespace cocoon bool get_relationship(URLRelationship* out_relationship, const URL& directory_url, const URL& other_url) const; /** * @brief Calls `-[NSFileManager homeDirectoryForUser:]`. - * @details Returns the home directory for the specified user. - Parameters: - userName: The username of the owner of the desired home directory. - Returns: A URL object containing the location of the specified user's home directory, or 'nil' if no such user exists or the user's home directory is not available. * @param user_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URL home_directory_for_user(const std::string& user_name) const; /** * @brief Calls `-[NSFileManager isDeletableFileAtPath:]`. - * @details Returns a Boolean value that indicates whether the invoking object appears able to delete a specified file. - Parameters: - path: A file path. - Returns: 'YES' if the current process has delete privileges for the file at 'path'; otherwise 'NO' if the process does not have delete privileges or the existence of the file could not be determined. For a directory or file to be deletable, the current process must either be able to write to the parent directory of 'path' or it must have the same owner as the item at 'path'. If 'path' is a directory, every item contained in 'path' must be deletable by the current process. If the file at 'path' is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns 'NO'. If the item at 'path' is a symbolic link, it is not traversed. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_deletable_file_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager isExecutableFileAtPath:]`. - * @details Returns a Boolean value that indicates whether the operating system appears able to execute a specified file. - Parameters: - path: A file path. - Returns: 'YES' if the current process has execute privileges for the file at 'path'; otherwise 'NO' if the process does not have execute privileges or the existence of the file could not be determined. If the file at 'path' is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns 'NO'. This method traverses symbolic links in the path. This method also uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is executable. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_executable_file_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager isReadableFileAtPath:]`. - * @details Returns a Boolean value that indicates whether the invoking object appears able to read a specified file. - Parameters: - path: A file path. - Returns: 'YES' if the current process has read privileges for the file at 'path'; otherwise 'NO' if the process does not have read privileges or the existence of the file could not be determined. If the file at 'path' is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns 'NO'. This method traverses symbolic links in the path. This method also uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is readable. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_readable_file_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager isUbiquitousItemAtURL:]`. - * @details Returns a Boolean indicating whether the item is targeted for storage in iCloud. - Parameters: - url: Specify the URL for the file or directory whose status you want to check. - Returns: 'YES' if the item is targeted for iCloud storage or 'NO' if it is not. This method also returns 'NO' if no item exists at 'url'. This method reflects only whether the item should be stored in iCloud because a call was made to the 'setUbiquitous:itemAtURL:destinationURL:error:' method with a value of 'YES' for its 'flag' parameter. This method does not reflect whether the file has actually been uploaded to any iCloud servers. To determine a file's upload status, check the 'NSURLUbiquitousItemIsUploadedKey' attribute of the corresponding ''NSURL'' object. + * @details Returns YES if the item for the specified URL is ubiquitous, NO otherwise. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_ubiquitous_item_at_url(const URL& url) const; /** * @brief Calls `-[NSFileManager isWritableFileAtPath:]`. - * @details Returns a Boolean value that indicates whether the invoking object appears able to write to a specified file. - Parameters: - path: A file path. - Returns: 'YES' if the current process has write privileges for the file at 'path'; otherwise 'NO' if the process does not have write privileges or the existence of the file could not be determined. If the file at 'path' is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns 'NO'. This method traverses symbolic links in the path. This method also uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is writable. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_writable_file_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager linkItemAtPath:toPath:error:]`. - * @details Creates a hard link between the items at the specified paths. - Parameters: - srcPath: The path that specifies the item you wish to link to. The value in this parameter must not be 'nil'. - dstPath: The path that identifies the location where the link will be created. The value in this parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the hard link was created or 'NO' if an error occurred. This method also returns 'NO' if a file, directory, or link already exists at 'dstPath'. Use this method to create hard links between files in the current file system. If 'srcPath' is a directory, this method creates a new directory at 'dstPath' and then creates hard links for the items in that directory. If 'srcPath' is (or contains) a symbolic link, the symbolic link is copied to the new location and not converted to a hard link. Prior to linking each item, the file manager asks its delegate if it should actually create the link. It does this by calling the 'fileManager:shouldLinkItemAtURL:toURL:' method; if that method is not implemented it calls the 'fileManager:shouldLinkItemAtPath:toPath:' method instead. If the delegate method returns 'YES', or if the delegate does not implement the appropriate methods, the file manager creates the hard link. If there is an error linking one out of several items, the file manager may also call the delegate's 'fileManager:shouldProceedAfterError:linkingItemAtURL:toURL:' or 'fileManager:shouldProceedAfterError:linkingItemAtPath:toPath:' method to determine how to proceed. * @param src_path Argument converted to the Objective-C parameter of the same role. * @param dst_path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -352,7 +342,6 @@ namespace cocoon bool link_item_at_path(const std::string& src_path, const std::string& dst_path) const; /** * @brief Calls `-[NSFileManager linkItemAtURL:toURL:error:]`. - * @details Creates a hard link between the items at the specified URLs. - Parameters: - srcURL: The file URL that identifies the source of the link. The URL in this parameter must not be a file reference URL; it must specify the actual path to the item. The value in this parameter must not be 'nil'. - dstURL: The file URL that specifies where you want to create the hard link. The URL in this parameter must not be a file reference URL; it must specify the actual path to the item. The value in this parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the hard link was created or 'NO' if an error occurred. This method also returns 'NO' if a file, directory, or link already exists at 'dstURL'. Use this method to create hard links between files in the current file system. If 'srcURL' is a directory, this method creates a new directory at 'dstURL' and then creates hard links for the items in that directory. If 'srcURL' is (or contains) a symbolic link, the symbolic link is copied and not converted to a hard link at 'dstURL'. * @param src_url Argument converted to the Objective-C parameter of the same role. * @param dst_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -360,7 +349,7 @@ namespace cocoon bool link_item_at_url(const URL& src_url, const URL& dst_url) const; /** * @brief Calls `-[NSFileManager mountedVolumeURLsIncludingResourceValuesForKeys:options:]`. - * @details Returns an array of URLs that identify the mounted volumes available on the device. - Parameters: - propertyKeys: An array of keys that identify the file properties that you want pre-fetched for each volume. For each returned URL, the values for these keys are cached in the corresponding ''NSURL'' objects. You may specify 'nil' for this parameter. For a list of keys you can specify, see Common File System Resource Keys. - options: Option flags for the enumeration. For a list of possible values, see ''FileManager/VolumeEnumerationOptions''. - Returns: An array of 'NSURL' objects identifying the mounted volumes. > Important: > This method returns 'nil' on platforms other than macOS. This call may block if I/O is required to determine values for the requested 'propertyKeys'. + * @details -mountedVolumeURLsIncludingResourceValuesForKeys:options: returns an NSArray of NSURLs locating the mounted volumes available on the computer. The property keys that can be requested are available in \. * @param property_keys Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -368,7 +357,6 @@ namespace cocoon std::vector mounted_volume_ur_ls_including_resource_values_for_keys(const std::vector& property_keys, VolumeEnumerationOptions options) const; /** * @brief Calls `-[NSFileManager moveItemAtPath:toPath:error:]`. - * @details Moves the file or directory at the specified path to a new location synchronously. - Parameters: - srcPath: The path to the file or directory you want to move. This parameter must not be 'nil'. - dstPath: The new path for the item in 'srcPath'. This path must include the name of the file or directory in its new location. This parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the item was moved successfully or the file manager's delegate stopped the operation deliberately. Returns 'NO' if an error occurred. When moving items, the current process must have permission to read the item at 'srcPath' and write the parent directory of 'dstPath'. If the item at 'srcPath' is a directory, this method moves the directory and all of its contents, including any hidden files. If an item with the same name already exists at 'dstPath', this method stops the move attempt and returns an appropriate error. If the last component of 'srcPath' is a symbolic link, only the link is moved to the new path; the item pointed to by the link remains at its current location. Prior to moving the item, the file manager asks its delegate if it should actually move it. It does this by calling the 'fileManager:shouldMoveItemAtURL:toURL:' method; if that method is not implemented it calls the 'fileManager:shouldMoveItemAtPath:toPath:' method instead. If the item being moved is a directory, the file manager notifies the delegate only for the directory itself and not for any of its contents. If the delegate method returns 'YES', or if the delegate does not implement the appropriate methods, the file manager moves the file. If there is an error moving one out of several items, the file manager may also call the delegate's 'fileManager:shouldProceedAfterError:movingItemAtURL:toURL:' or 'fileManager:shouldProceedAfterError:movingItemAtPath:toPath:' method to determine how to proceed. If the source and destination of the move operation are not on the same volume, this method copies the item first and then removes it from its current location. This behavior may trigger additional delegate notifications related to copying and removing individual items. * @param src_path Argument converted to the Objective-C parameter of the same role. * @param dst_path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -376,7 +364,6 @@ namespace cocoon bool move_item_at_path(const std::string& src_path, const std::string& dst_path) const; /** * @brief Calls `-[NSFileManager moveItemAtURL:toURL:error:]`. - * @details Moves the file or directory at the specified URL to a new location synchronously. - Parameters: - srcURL: The file URL that identifies the file or directory you want to move. The URL in this parameter must not be a file reference URL. This parameter must not be 'nil'. - dstURL: The new location for the item in 'srcURL'. The URL in this parameter must not be a file reference URL and must include the name of the file or directory in its new location. This parameter must not be 'nil'. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the item was moved successfully or the file manager's delegate stopped the operation deliberately. Returns 'NO' if an error occurred. When moving items, the current process must have permission to read the item at 'srcURL' and write the parent directory of 'dstURL'. If the item at 'srcURL' is a directory, this method moves the directory and all of its contents, including any hidden files. If an item with the same name already exists at 'dstURL', this method stops the move attempt and returns an appropriate error. If the last component of 'srcURL' is a symbolic link, only the link is moved to the new path; the item pointed to by the link remains at its current location. If the source and destination of the move operation are not on the same volume, this method copies the item first and then removes it from its current location. This behavior may trigger additional delegate notifications related to copying and removing individual items. * @param src_url Argument converted to the Objective-C parameter of the same role. * @param dst_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -391,21 +378,19 @@ namespace cocoon void pause_sync_for_ubiquitous_item_at_url(const URL& url, std::function completion_handler) const; /** * @brief Calls `-[NSFileManager removeItemAtPath:error:]`. - * @details Removes the file or directory at the specified path. - Parameters: - path: A path string indicating the file or directory to remove. If the path specifies a directory, the contents of that directory are recursively removed. You may specify 'nil' for this parameter in Objective-C. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the item was removed successfully or if 'path' was 'nil'. Returns 'NO' if an error occurred. If the delegate stops the operation for a file, this method returns 'YES'. However, if the delegate stops the operation for a directory, this method returns 'NO'. Prior to removing each item, the file manager asks its delegate if it should actually do so. It does this by calling the 'fileManager:shouldRemoveItemAtURL:' method; if that method is not implemented it calls the 'fileManager:shouldRemoveItemAtPath:' method instead. If the delegate method returns 'YES', or if the delegate does not implement the appropriate methods, the file manager proceeds to remove the file or directory. If there is an error removing an item, the file manager may also call the delegate's 'fileManager:shouldProceedAfterError:removingItemAtURL:' or 'fileManager:shouldProceedAfterError:removingItemAtPath:' method to determine how to proceed. Removing an item also removes all old versions of that item, invalidating any URLs returned by the 'URLForPublishingUbiquitousItemAtURL:expirationDate:error:' method to old versions. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool remove_item_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager removeItemAtURL:error:]`. - * @details Removes the file or directory at the specified URL. - Parameters: - URL: A file URL specifying the file or directory to remove. If the URL specifies a directory, the contents of that directory are recursively removed. You may specify 'nil' for this parameter in Objective-C. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the item was removed successfully or if 'URL' was 'nil'. Returns 'NO' if an error occurred. If the delegate stops the operation for a file, this method returns 'YES'. However, if the delegate stops the operation for a directory, this method returns 'NO'. Prior to removing each item, the file manager asks its delegate if it should actually do so. It does this by calling the 'fileManager:shouldRemoveItemAtURL:' method; if that method is not implemented it calls the 'fileManager:shouldRemoveItemAtPath:' method instead. Removing an item also removes all old versions of that item, invalidating any URLs returned by the 'URLForPublishingUbiquitousItemAtURL:expirationDate:error:' method to old versions. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool remove_item_at_url(const URL& url) const; /** * @brief Calls `-[NSFileManager replaceItemAtURL:withItemAtURL:backupItemName:options:resultingItemURL:error:]`. - * @details Replaces the contents of the item at the specified URL in a manner that ensures no data loss occurs. - Parameters: - originalItemURL: The item containing the content you want to replace. - newItemURL: The item containing the new content for 'originalItemURL'. It is recommended that you put this item in a temporary directory as provided by the OS. If a temporary directory is not available, put this item in a uniquely named directory that is in the same directory as the original item. - backupItemName: If provided, the name used to create a backup of the original item. The backup is placed in the same directory as the original item. If an error occurs during the creation of the backup item, the operation fails. If there is already an item with the same name as the backup item, that item will be removed. The backup item will be removed in the event of success unless the 'NSFileManagerItemReplacementWithoutDeletingBackupItem' option is provided in 'options'. - options: The options to use during the replacement. Typically, you pass 'NSFileManagerItemReplacementUsingNewMetadataOnly' for this parameter, which uses only the metadata from the new item. Pass '0' to get the default behavior, which uses only the metadata from the new item while adjusting some properties using values from the original item. - resultingURL: On input, a pointer for a URL object. When the item is replaced, this pointer is set to the URL of the new item. If no new file system object is required, the URL object in this parameter may be the same passed to the 'originalItemURL' parameter. However, if a new file system object is required, the URL object may be different. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the replacement was successful or 'NO' if an error occurred. By default, the creation date, permissions, Finder label and color, and Spotlight comments of the original item are preserved on the new item. You can configure which metadata is preserved using the 'options' parameter. This method works only when the 'originalItemURL' and 'newItemURL' parameters are located on the same volume. Attempting to call this method by passing 'originalItemURL' and 'newItemURL' parameters that have locations on different volumes results in an error. Instead, you can call the 'URLForDirectory:inDomain:appropriateForURL:create:error:' method, passing 'NSItemReplacementDirectory' as the search path directory, to get a temporary URL on the destination's volume that is suitable for use with this method. If an error occurs and the original item is not in the original location or a temporary location, the resulting error object contains a user info dictionary with the key '"NSFileOriginalItemLocationKey"'. The value assigned to that key is an ''NSURL'' object with the location of the item. + * @details -replaceItemAtURL:withItemAtURL:backupItemName:options:resultingItemURL:error: is for developers who wish to perform a safe-save without using the full NSDocument machinery that is available in the AppKit. The 'originalItemURL' is the item being replaced. 'newItemURL' is the item which will replace the original item. This item should be placed in a temporary directory as provided by the OS, or in a uniquely named directory placed in the same directory as the original item if the temporary directory is not available. If 'backupItemName' is provided, that name will be used to create a backup of the original item. The backup is placed in the same directory as the original item. If an error occurs during the creation of the backup item, the operation will fail. If there is already an item with the same name as the backup item, that item will be removed. The backup item will be removed in the event of success unless the 'NSFileManagerItemReplacementWithoutDeletingBackupItem' option is provided in 'options'. For 'options', pass '0' to get the default behavior, which uses only the metadata from the new item while adjusting some properties using values from the original item. Pass 'NSFileManagerItemReplacementUsingNewMetadataOnly' in order to use all possible metadata from the new item. * @param original_item_url Argument converted to the Objective-C parameter of the same role. * @param new_item_url Argument converted to the Objective-C parameter of the same role. * @param backup_item_name Argument converted to the Objective-C parameter of the same role. @@ -424,7 +409,7 @@ namespace cocoon void resume_sync_for_ubiquitous_item_at_url(const URL& url, FileManagerResumeSyncBehavior behavior, std::function completion_handler) const; /** * @brief Calls `-[NSFileManager setAttributes:ofItemAtPath:error:]`. - * @details Sets the attributes of the specified file or directory. - Parameters: - attributes: A dictionary containing as keys the attributes to set for 'path' and as values the corresponding value for the attribute. You can set the following attributes: 'NSFileBusy', 'NSFileCreationDate', 'NSFileExtensionHidden', 'NSFileGroupOwnerAccountID', 'NSFileGroupOwnerAccountName', 'NSFileHFSCreatorCode', 'NSFileHFSTypeCode', 'NSFileImmutable', 'NSFileModificationDate', 'NSFileOwnerAccountID', 'NSFileOwnerAccountName', 'NSFilePosixPermissions'. You can change single attributes or any combination of attributes; you need not specify keys for all attributes. - path: The path of a file or directory. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if all changes succeed. If any change fails, returns 'NO', but it is undefined whether any changes actually occurred. As in the POSIX standard, the app either must own the file or directory or must be running as superuser for attribute changes to take effect. The method attempts to make all changes specified in attributes and ignores any rejection of an attempted modification. If the last component of the path is a symbolic link, the system traverses it. You must initialize the 'NSFilePosixPermissions' value with the code representing the POSIX file-permissions bit pattern. The system sets 'NSFileHFSCreatorCode' and 'NSFileHFSTypeCode' only when 'path' specifies a file. + * @details setAttributes:ofItemAtPath:error: returns YES when the attributes specified in the 'attributes' dictionary are set successfully on the item specified by 'path'. If this method returns NO, a presentable NSError will be provided by-reference in the 'error' parameter. If no error is required, you may pass 'nil' for the error. This method replaces changeFileAttributes:atPath:. * @param attributes Argument converted to the Objective-C parameter of the same role. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -432,7 +417,7 @@ namespace cocoon bool set_attributes(const std::map& attributes, const std::string& path) const; /** * @brief Calls `-[NSFileManager setUbiquitous:itemAtURL:destinationURL:error:]`. - * @details Indicates whether the item at the specified URL should be stored in iCloud. - Parameters: - flag: 'YES' to move the item to iCloud or 'NO' to remove it from iCloud (if it is there currently). - url: The URL of the item (file or directory) that you want to store in iCloud. - destinationURL: When moving a file into iCloud, this is the location in iCloud at which to store the file or directory. This URL must be constructed from a URL returned by the 'URLForUbiquityContainerIdentifier:' method. When moving a file out of iCloud, this is the location on the local device. - error: On input, a pointer to variable for an ''NSError'' object. If an error occurs, this pointer is set to an ''NSError'' object containing information about the error. You may specify 'nil' to ignore the error information. - Returns: 'YES' if the item's status was updated successfully or 'NO' if an error occurred. Use this method to move a file from its current location to iCloud. For files located in an app's sandbox, this involves physically removing the file from the sandbox container. You can also use this method to move files out of iCloud and back into a local directory. > Important: > Avoid calling this method from your app's main thread. This method performs a coordinated write operation on the specified file, which can block for a long time. Instead, use a dispatch queue to call this method from background thread. + * @details Changes whether the item for the specified URL is ubiquitous and moves the item to the destination URL. When making an item ubiquitous, the destination URL must be prefixed with a URL from -URLForUbiquityContainerIdentifier:. Returns YES if the change is successful, NO otherwise. * @param flag Argument converted to the Objective-C parameter of the same role. * @param url Argument converted to the Objective-C parameter of the same role. * @param destination_url Argument converted to the Objective-C parameter of the same role. @@ -441,14 +426,14 @@ namespace cocoon bool set_ubiquitous(bool flag, const URL& url, const URL& destination_url) const; /** * @brief Calls `-[NSFileManager startDownloadingUbiquitousItemAtURL:error:]`. - * @details Starts downloading (if necessary) the specified item to the local system. - Parameters: - url: The URL for the file or directory in the cloud that you want to download. - error: On input, a pointer to variable for an ''NSError'' object. If an error occurs, this pointer is set to an ''NSError'' object containing information about the error. You may specify 'nil' to ignore the error information. - Returns: 'YES' if the download started successfully or was not necessary, 'NO' otherwise. If a cloud-based file or directory has not been downloaded yet, calling this method starts the download process. If the item exists locally, calling this method synchronizes the local copy with the version in the cloud. + * @details Start downloading a local instance of the specified ubiquitous item, if necessary. Returns YES if the download started successfully or wasn't necessary, NO otherwise. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool start_downloading_ubiquitous_item_at_url(const URL& url) const; /** * @brief Calls `-[NSFileManager stringWithFileSystemRepresentation:length:]`. - * @details Returns an ''NSString'' object whose contents are derived from the specified C-string path. - Parameters: - str: A C string representation of a pathname. - len: The number of characters in 'string'. - Returns: An ''NSString'' object converted from the C-string representation 'string' with length 'len' of a pathname in the current file system. Use this method if your code receives paths as C strings from system routines. + * @details stringWithFileSystemRepresentation:length: returns an NSString created from an array of bytes that are in the filesystem representation. * @param str Argument converted to the Objective-C parameter of the same role. * @param len Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -456,21 +441,21 @@ namespace cocoon std::string string_with_file_system_representation(const std::string& str, std::uint64_t len) const; /** * @brief Calls `-[NSFileManager subpathsAtPath:]`. - * @details Returns an array of strings identifying the paths for all items in the specified directory. - Parameters: - path: The path of the directory to list. - Returns: An array of ''NSString'' objects, each of which contains the path of an item in the directory specified by 'path'. If 'path' is a symbolic link, this method traverses the link. This method returns 'nil' if it cannot retrieve the device of the linked-to file. This method recurses the specified directory and its subdirectories. The method skips the "'.'" and "'..'" directories at each level of the recursion. This method reveals every element of the subtree at 'path', including the contents of file packages (such as apps, nib files, and RTFD files). In macOS 10.5 and later, use 'subpathsOfDirectoryAtPath:error:' instead. + * @details subpathsAtPath: returns an NSArray of all contents and subpaths recursively from the provided path. This may be very expensive to compute for deep filesystem hierarchies, and should probably be avoided. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector subpaths_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager subpathsOfDirectoryAtPath:error:]`. - * @details Performs a deep enumeration of the specified directory and returns the paths of all of the contained subdirectories. - Parameters: - path: The path of the directory to list. - error: If an error occurs, upon return contains an ''NSError'' object that describes the problem. Pass 'NULL' if you don't want error information. - Returns: An array of strings, each containing the path of an item in the directory specified by 'path'. When using Objective-C, returns 'nil' if an error occurred. This method recurses the specified directory and its subdirectories. The method skips the "'.'" and "'..'" directories at each level of the recursion. Because this method recurses the directory's contents, you might not want to use it in performance-critical code. Instead, consider using the ''NSFileManager/enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:'' or ''FileManager/enumerator(atPath:)'' method to enumerate the directory contents yourself. Doing so gives you more control over the retrieval of items and more opportunities to complete the enumeration or perform other tasks at the same time. + * @details subpathsOfDirectoryAtPath:error: returns an NSArray of NSStrings representing the filenames of the items in the specified directory and all its subdirectories recursively. If this method returns 'nil', an NSError will be returned by reference in the 'error' parameter. If the directory contains no items, this method will return the empty array. This method replaces subpathsAtPath: * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector subpaths_of_directory_at_path(const std::string& path) const; /** * @brief Calls `-[NSFileManager trashItemAtURL:resultingItemURL:error:]`. - * @details Moves an item to the trash. - Parameters: - url: The item to move to the trash. - outResultingURL: On input, a pointer to a URL object. On output, this pointer is set to the item's location in the trash. The actual name of the item may be changed when moving it to the trash, so use this URL to access it. You may specify 'nil' for this parameter if you do not want the information. - error: On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify 'nil' for this parameter if you do not want the error information. - Returns: 'YES' if the item at 'url' was successfully moved to the trash, or 'NO' if the item was not moved to the trash. + * @details trashItemAtURL:resultingItemURL:error: returns YES if the item at 'url' was successfully moved to a Trash. Since the operation may require renaming the file to avoid collisions, it also returns by reference the resulting URL that the item was moved to. If this method returns NO, the item was not moved and an NSError will be returned by reference in the 'error' parameter. To easily discover if an item is in the Trash, you may use [fileManager getRelationship:&result ofDirectory:NSTrashDirectory inDomain:0 toItemAtURL:url error:&error] && result == NSURLRelationshipContains. * @param url Argument converted to the Objective-C parameter of the same role. * @param out_resulting_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -478,7 +463,7 @@ namespace cocoon bool trash_item_at_url(const URL& url, URL& out_resulting_url) const; /** * @brief Calls `-[NSFileManager unmountVolumeAtURL:options:completionHandler:]`. - * @details Starts the process of unmounting the specified volume. - Parameters: - url: A file URL specifying the volume to be unmounted. - mask: A bitmask of ''FileManager/UnmountOptions'' that you can use to customize the unmount operation’s behavior. - completionHandler: A block executed when the unmount operation completes. The block receives an error parameter which is 'nil' if unmounting was successful. Otherwise, it indicates why unmounting failed. If the volume is encrypted, it is relocked after being unmounted. + * @details This method starts the process of unmounting the volume specified by url. If the volume is encrypted, it is re-locked after being unmounted. The completionHandler will be executed when the operation is complete. If the operation was successful, the block’s errorOrNil argument will be nil; otherwise, errorOrNil will be an error object indicating why the unmount operation failed. * @param url Argument converted to the Objective-C parameter of the same role. * @param mask Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. @@ -494,25 +479,23 @@ namespace cocoon void upload_local_version_of_ubiquitous_item_at_url(const URL& url, FileManagerUploadLocalVersionConflictPolicy conflict_resolution_policy, std::function completion_handler) const; /** * @brief Returns the `currentDirectoryPath` property of `NSFileManager`. - * @details The path to the program's current directory. The current directory path is the starting point for any relative paths you specify. For example, if the current directory is '/tmp' and you specify a relative pathname of 'reports/info.txt', the resulting full path for the item is '/tmp/reports/info.txt'. When an app is launched, this property is initially set to the app's current working directory. If the current working directory is not accessible for any reason, the value of this property is 'nil'. You can change the value of this property by calling the 'changeCurrentDirectoryPath:' method. > Warning: > This property reports the current working directory for the current process, not just the receiver. + * @details Process working directory management. Despite the fact that these are instance methods on NSFileManager, these methods report and change (respectively) the working directory for the entire process. Developers are cautioned that doing so is fraught with peril. * @return The converted Objective-C result. */ std::string current_directory_path() const; /** * @brief Returns the `defaultManager` property of `NSFileManager`. - * @details The shared file manager object for the process. This method always represents the same file manager object. If you plan to use a delegate with the file manager to receive notifications about the completion of file-based operations, you should create a new instance of ''FileManager'' rather than using the shared object. + * @details Returns the default singleton instance. * @return The converted Objective-C result. */ static FileManager default_manager(); /** * @brief Returns the `homeDirectoryForCurrentUser` property of `NSFileManager`. - * @details The home directory for the current user. * @return The converted Objective-C result. */ URL home_directory_for_current_user() const; /** * @brief Returns the `temporaryDirectory` property of `NSFileManager`. - * @details The temporary directory for the current user. * @return The converted Objective-C result. */ URL temporary_directory() const; diff --git a/include/generated/file_provider_service.h b/include/generated/file_provider_service.h index 184dcb19..f78cf6ac 100644 --- a/include/generated/file_provider_service.h +++ b/include/generated/file_provider_service.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFileProviderService` (Foundation). - * @details A service that provides a custom communication channel between your app and a File Provider extension. To communicate, both your app and the File Provider extension must implement their part of the service: - Your app requests the proxy object, and calls its methods. - The File Provider extension declares the supported services and vends a proxy object that implements the protocol for each service. The app and File Provider extension communicate using an XPC service. This service performs actions only on items managed by the File Provider extension. For more information, see [Creating XPC Services](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingXPCServices.html\#//apple_ref/doc/uid/10000172i-SW6). \#\#\# Defining the Service’s Protocol Services let you define custom actions that are not provided by Apple's APIs. Both the app and the File Provider extension must agree upon the service's name and protocol. Communicate the name and protocol through an outside source (for example, posting a header file that defines both the name and protocol, or publishing a library that includes them both). The service can be defined by either the app or the File Provider extension: - Apps can define a service for features they would like to use. File providers can then choose to support those features by implementing the service. - File Provider extensions can provide a service for the features they support. Apps can then choose to use the specified service. When defining a service's protocol, the parameters for each method must adhere to the following rules: - The parameter's class must conform to ''NSSecureCoding''. - The parameter's class must be defined in both the app and the File Provider extension (for example, standard system types or classes defined in a library imported by both sides). - If a collection parameter contains types other than property list types (see [Property List Types and Objects](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/PropertyList.html\#//apple_ref/doc/uid/TP40008195-CH44-SW2)), declare the valid types using the ''NSXPCInterface'' class's ''NSXPCInterface/classes(for:argumentIndex:ofReply:)'' method. + * @details In an application that has received a URL to a file owned by a file provider, instances of NSFileProviderService can by obtained by calling -[NSFileManager getFileProviderServicesForItemAtURL:completionHandler:]. Each NSFileProviderService instance can only be used to operate on the URL originally passed to that method. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -35,13 +35,11 @@ namespace cocoon explicit FileProviderService(Adopt adopt); /** * @brief Calls `-[NSFileProviderService getFileProviderConnectionWithCompletionHandler:]`. - * @details Asynchronously returns the service's connection object. - Parameters: - completionHandler: A block that is called on an anonymous background queue. The block receives the 'NSXPCConnection' object for the service, or 'nil' if an error occurs, and an 'NSError' describing the error if one occurred. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void get_file_provider_connection_with_completion_handler(std::function completion_handler) const; /** * @brief Returns the `name` property of `NSFileProviderService`. - * @details The File Provider service's name. * @return The converted Objective-C result. */ std::string name() const; diff --git a/include/generated/file_security.h b/include/generated/file_security.h index 19f8a34b..a132c779 100644 --- a/include/generated/file_security.h +++ b/include/generated/file_security.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSFileSecurity` (Foundation). - * @details A stub class that encapsulates security information about a file. ''NSFileSecurity'' contains no methods of its own. Instead, it is transparently bridged to \. + * @details NSFileSecurity encapsulates a file system object's security information. NSFileSecurity and CFFileSecurity are toll-free bridged. Use the CFFileSecurity API for access to the low-level file security properties encapsulated by NSFileSecurity. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example diff --git a/include/generated/file_version.h b/include/generated/file_version.h index c54df4dc..0ac79954 100644 --- a/include/generated/file_version.h +++ b/include/generated/file_version.h @@ -15,7 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFileVersion` (Foundation). - * @details A snapshot of a file at a specific point in time. Use the methods of this class to access, create, and manage file revisions in your app. Each file version instance contains metadata about a single revision, including the location of the associated file, the modification date of the revision, and whether the revision is discardable. In Mac apps, you can use file version objects to track changes to a local file over time and to prevent the loss of data during editing. When managing local versions, the document architecture creates versions at specific points in the lifetime of your application. Your application can also create versions explicitly at times that your application designates as appropriate. In addition to managing local files, the system also uses this class to manage cloud-based files. For files in the cloud, there is usually only one version of the file at any given time. However, additional file versions may be created in cases where two different computers attempt to save the file to the cloud at the same time. In that case, one file is chosen as the current version and any other versions are tagged as being in conflict with the original. Conflict versions are reported to the appropriate file presenter objects and should be resolved as soon as possible so that the corresponding files can be removed from the cloud. + * @details Instances of NSFileVersion for the same version of the same file are equal, and instances of NSFileVersion for different versions of the same file are not equal, but the equality of NSFileVersions for different files is undefined. Repeated invocations of the methods that return NSFileVersions do not necessarily return the exact same instance of NSFileVersion. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -52,7 +52,7 @@ namespace cocoon explicit FileVersion(Adopt adopt); /** * @brief Calls `+[NSFileVersion addVersionOfItemAtURL:withContentsOfURL:options:error:]`. - * @details Creates a version of the file at the specified location. You can use this method to save a version of your file to the location specified by the url parameter. The contents of the file are taken from the contentsURL parameter, whose value may be the same as the url parameter. You should always add file versions as part of a coordinated write operation to a file. In other words, always call this method from a block passed to a file coordinator object to initiate a write operation. Doing so ensures that no other processes are operating on the file while you save the version to its new location. You can add versions only on Mac OS X. + * @details Add a new version of the file located by a URL, with the contents coming from a file located by either the same or a different URL, and return a new instance that represents the version if successful. If not successful, return NO after setting outError to an NSError that encapsulates why not. You can add versions only on Mac OS X. When adding or removing versions of a file you should do it as part of a "coordinated" write to the file. The NSFileCoordinator class that you use to do coordinated file access is declared in \. Using it properly ensures that NSFilePresenters of the file, or directories that contain the file, receive accurate notifications about versions being added or removed. NSFilePresenter is declared in \. For example, use -[NSFileCoordinator coordinateWritingItemAtURL:options:error:byAccessor:] when the file URL and the contents url are the same. (NSFileVersion doesn't simply use NSFileCoordinator itself because that would be insufficient when the adding or removing of versions is part of a larger operation that should be treated as one coordinated file access.) * @param url Argument converted to the Objective-C parameter of the same role. * @param contents_url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. @@ -61,41 +61,41 @@ namespace cocoon static FileVersion add_version_of_item_at_url(const URL& url, const URL& contents_url, FileVersionAddingOptions options); /** * @brief Calls `+[NSFileVersion currentVersionOfItemAtURL:]`. - * @details Returns the most recent version object for the file at the specified URL. - Parameter url: The URL of the file whose version object you want. - Returns: The version object representing the current version of the file or nil if there is no such file. + * @details Return an NSFileVersion that represents the contents of the file located by a URL, or nil if there is no such file. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static FileVersion current_version_of_item_at_url(const URL& url); /** * @brief Calls `+[NSFileVersion getNonlocalVersionsOfItemAtURL:completionHandler:]`. - * @details Asynchronously returns an array of NSFileVersions associated with the file located by the given URL, or nil if there is no such file or another error occurs. Versions returned by this method do not initially have their contents stored locally on the device, so a download may be required before you are able to access them. File attributes are accessible via -[NSURL getPromisedItemResourceValue:forKey:error:]. You can request a download by performing a coordinated read with NSFileCoordinator on the URL property of the resulting NSFileVersions. When a version is successfully downloaded, its contents are cached locally, and the version will no longer be returned by this method. The version will be returned by +otherVersionsOfItemAtURL: instead, but will retain the same persistentIdentifier value. + * @details Asynchronously return an array of NSFileVersions associated with the file located by the given URL, or nil if there is no such file or another error occurs. Versions returned by this method do not initially have their contents stored locally on the device, so a download may be required before you are able to access them. File attributes are accessible via -[NSURL getPromisedItemResourceValue:forKey:error:]. You can request a download by performing a coordinated read with NSFileCoordinator on the URL property of the resulting NSFileVersions. When a version is successfully downloaded, its contents are cached locally, and the version will no longer be returned by this method. The version will be returned by +[NSFileVersion otherVersionsOfItemAtURL:] instead, but will retain the same persistentIdentifier value. If the local version is later discarded, future invocations of this method may resume returning the version. If you need to get all versions for a document, both local and non-local, you should use an NSFilePresenter that implements -presentedItemDidGainVersion: and -presentedItemDidLoseVersion: and invoke +[NSFileCoordinator addFilePresenter:], +[NSFileVersion otherVersionsOfItemAtURL:], and this method within a single coordinated read. * @param url Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ static void get_nonlocal_versions_of_item_at_url(const URL& url, std::function, Error)> completion_handler); /** * @brief Calls `+[NSFileVersion otherVersionsOfItemAtURL:]`. - * @details Returns all versions of the specified file except the current version. - Parameter url: The URL of the file whose versions you want. - Returns: An array of file version objects or nil if there is no such file. The array does not contain the version object returned by the +currentVersionOfItemAtURL: method. For locally based files, this property typically contains versions of the file that you saved explicitly or that were saved at appropriate times while the file was being edited. For documents residing in the cloud, this property typically returns zero or more file versions representing conflicting versions of a file that need to be resolved with the current version. + * @details Return an array of NSFileVersions associated with the file located by a URL, or nil if there is no such file. The array never contains an NSFileVersion equal to what +currentVersionOfItemAtURL: would return. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector other_versions_of_item_at_url(const URL& url); /** * @brief Calls `-[NSFileVersion removeAndReturnError:]`. - * @details Remove this version object and its associated file from the version store. This method removes this version object and its file from the version store, freeing up the associated storage space. You must not call this method for the current file version — that is, the version object returned by the +currentVersionOfItemAtURL: method. You should always remove file versions as part of a coordinated write operation to a file. Doing so ensures that no other processes are operating on the file while you remove the version information. If successful, subsequent requests for the versions of the file do not include this version object. + * @details Delete the receiver's storage, and return YES if successful. If not successful, return NO after setting outError to an NSError that encapsulates why not. Subsequent invocations of +versionsOfItemAtURL: won't include an NSFileVersion for a successfully removed version. You cannot use this method to delete the versioned file itself. This method always throws an exception when sent to the result of invoking +currentVersionOfItemAtURL:. Use -[NSFileManager removeItemAtURL:error:] for that instead. When removing versions of a file you should do it as part of a coordinated write to the file. The advice about this for +addVersionOfItemAtURL:withContentsOfURL:options:error: applies here too. * @return The converted Objective-C result. */ bool remove_and_return_error() const; /** * @brief Calls `+[NSFileVersion removeOtherVersionsOfItemAtURL:error:]`. - * @details Removes all versions of a file, except the current one, from the version store. This method removes all versions except the current one from the version store, freeing up the associated storage space. You should always remove file versions as part of a coordinated write operation to a file. Doing so ensures that no other processes are operating on the file while you remove the version information. If successful, subsequent requests for the versions of the file reflect that only the current version is available. + * @details Delete all of the versions associated with the file located by a URL, except for the current one, and return YES if successful. If not successful, return NO after setting outError to an NSError that encapsulates why not. When removing versions of a file you should do it as part of a coordinated write to the file. The advice about this for +addVersionOfItemAtURL:withContentsOfURL:options:error: applies here too. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool remove_other_versions_of_item_at_url(const URL& url); /** * @brief Calls `-[NSFileVersion replaceItemAtURL:options:error:]`. - * @details Replace the contents of the specified file with the contents of the current version's file. If the passed-in URL locates a file, replace the file with a file whose contents are taken from the version but whose display name is taken from the file. If the passed-in URL does not locate a file then simply write one. The one exception to taking the display name from an existing file is if the version is of a different type than the overwritten file, in which case the file name extension will be taken from the version. When you use NSFileVersionReplacingByMoving you remove a version of the file, and should do it as part of a coordinated write to the file. + * @details If the passed-in URL locates a file, replace the file with a file whose contents are taken from the version but whose display name is taken from the file. If the passed-in URL does not locate a file then simply write one. If successful, return a URL that locates the resulting file; it may be different from the passed-in URL. The one exception to taking the display name from an existing file is if the version is of a different type than the overwritten file. In that case the file name extension will be taken from the version. (When file name extensions are being hidden in a user-friendly way this is not actually an exception.) If not successful, return NO after setting outError to an NSError that encapsulates why not. When you use NSFileVersionReplacingByMoving you remove a version of the file, and should do it as part of a coordinated write to the file. The advice about this for +addVersionOfItemAtURL:withContentsOfURL:options:error: applies here too. When you use it to promote a version to a separate file you actually write to two files, and should do it as part of a coordinated write to two files, using -[NSFileCoordinator coordinateWritingItemAtURL:options:writingItemAtURL:options:error:byAccessor:], most likely using NSFileCoordinatorWritingForReplacing for the file you're promoting the version to. * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -103,21 +103,21 @@ namespace cocoon URL replace_item_at_url(const URL& url, FileVersionReplacingOptions options) const; /** * @brief Calls `+[NSFileVersion temporaryDirectoryURLForNewVersionOfItemAtURL:]`. - * @details Creates and returns a temporary directory to use for saving the contents of the file. You can use this method in situations where you want to write the contents for a new file version in a temporary location. When you finish creating the temporary file within the returned directory, add it as a new version with -addVersionOfItemAtURL:withContentsOfURL:options:error: with the NSFileVersionAddingByMoving option. You must delete the directory returned by this method when you are done with it. + * @details Given a URL, create a new directory that is suitable for using as the container of a new temporary file that you will create and use with NSFileVersionAddingByMoving. This is useful when you want to create a new version of a file out of something other than the file's current contents, for example, the contents in memory of a document that has not yet been saved to its file. You must remove this directory when you are done with it, using -[NSFileManager removeItemAtURL:error:] for example. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URL temporary_directory_url_for_new_version_of_item_at_url(const URL& url); /** * @brief Calls `+[NSFileVersion unresolvedConflictVersionsOfItemAtURL:]`. - * @details Returns an array of version objects that are currently in conflict for the specified URL. - Parameter url: The URL of the file that has associated version objects. - Returns: An array of NSFileVersion objects that represent the versions in conflict or nil if the file at URL does not exist. + * @details Return an array of NSFileVersions that represent unresolved conflicts for the file located by a URL, or nil if there is no such file. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector unresolved_conflict_versions_of_item_at_url(const URL& url); /** * @brief Calls `+[NSFileVersion versionOfItemAtURL:forPersistentIdentifier:]`. - * @details Returns the version of the file that has the specified persistent ID. - Parameter url: The URL of the file whose version you want. - Parameter persistentIdentifier: The persistent ID of the NSFileVersion object you want. - Returns: The file version object with the specified ID or nil if no such version object exists. + * @details For a file located by a URL, return the NSFileVersion identified by a persistent identifier of the sort returned by -persistentIdentifier, or nil if the version no longer exists. * @param url Argument converted to the Objective-C parameter of the same role. * @param persistent_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -125,25 +125,25 @@ namespace cocoon static FileVersion version_of_item_at_url(const URL& url, const Object& persistent_identifier); /** * @brief Returns the `URL` property of `NSFileVersion`. - * @details The URL identifying the location of the file associated with the file version object. The URL identifies the location of the file associated with this version. If this version of the file has been deleted, the value in this property is nil. Do not display any part of this URL to the user. The location of file versions is managed by the system and should not be exposed to the user. If you want to present the name of a file version, use the localizedName property. + * @details The location of the receiver's storage, or possibly nil if the receiver's storage has been deleted. The storage is read-only. The URL will have an arcane path. You must not derive user-presentable text from it. * @return The converted Objective-C result. */ URL url() const; /** * @brief Returns the `conflict` property of `NSFileVersion`. - * @details A Boolean value indicating whether the contents of the version are in conflict with the contents of another version. When two or more versions of a file are written at the same time, perhaps because the file is saved in the cloud and one or more of the writers were offline when they were writing, the system attempts to resolve the conflict automatically. It does this by picking one of the file versions to be the current file and setting this property to YES for the other file versions that are in conflict. + * @details Whether the version was created as a result of the discovery of a conflict between two writers of the versioned file. * @return The converted Objective-C result. */ bool is_conflict() const; /** * @brief Returns the `discardable` property of `NSFileVersion`. - * @details A Boolean value that specifies whether the system can delete the associated file at some future time. Marking a file version as discardable gives the system the flexibility to reclaim the space, occupied by the associated file, at some future time. Do not, however, depend on the file being discarded. After setting this property to YES, do not set this property to NO again. Doing so causes the system to raise an exception. In addition, if you set this property to YES for the version of the file returned by the +currentVersionOfItemAtURL: method, the system raises an exception. Versions can be discardable only on Mac OS X. + * @details Whether the system is allowed to automatically delete the receiver's storage in the future, at an unpredictable time. Setting this to YES can fail so you must not depend on discarding for correct operation. Once you have indicated that a version is discardable you cannot make it undiscardable again. Setting this to NO causes an exception to be thrown. You cannot make the versioned file itself discardable. Setting the value of this property always throws an exception when sent to the result of invoking +currentVersionOfItemAtURL:. Versions can be discardable only on Mac OS X. * @return The converted Objective-C result. */ bool is_discardable() const; /** * @brief Sets the `discardable` property of `NSFileVersion`. - * @details A Boolean value that specifies whether the system can delete the associated file at some future time. Marking a file version as discardable gives the system the flexibility to reclaim the space, occupied by the associated file, at some future time. Do not, however, depend on the file being discarded. After setting this property to YES, do not set this property to NO again. Doing so causes the system to raise an exception. In addition, if you set this property to YES for the version of the file returned by the +currentVersionOfItemAtURL: method, the system raises an exception. Versions can be discardable only on Mac OS X. + * @details Whether the system is allowed to automatically delete the receiver's storage in the future, at an unpredictable time. Setting this to YES can fail so you must not depend on discarding for correct operation. Once you have indicated that a version is discardable you cannot make it undiscardable again. Setting this to NO causes an exception to be thrown. You cannot make the versioned file itself discardable. Setting the value of this property always throws an exception when sent to the result of invoking +currentVersionOfItemAtURL:. Versions can be discardable only on Mac OS X. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_discardable(bool value) const; @@ -161,13 +161,13 @@ namespace cocoon bool has_thumbnail() const; /** * @brief Returns the `localizedName` property of `NSFileVersion`. - * @details The string containing the user-presentable name of the file version. When displaying different versions of a file to the user, you should present this string to the user instead of the version's URL. + * @details The user-presentable name of the version, or possibly nil if the receiver's storage has been deleted. This will be different from the user-presentable name of the versioned file if, for example, the file has been renamed since the version was added. * @return The converted Objective-C result. */ std::string localized_name() const; /** * @brief Returns the `localizedNameOfSavingComputer` property of `NSFileVersion`. - * @details The user-presentable name of the computer on which the revision was saved. If the current revision has been deleted from disk, or if no computer name was recorded, the value in this property is nil. The computer name is guaranteed to be recorded only when the current version is in conflict with another version. The version object does not track changes to the computer name itself. Thus, if the computer name changed, the value in this string might be an old value. + * @details The user-presentable name of the computer on which the version was saved, or possibly nil if the receiver's storage has been deleted, or nil if no computer name was recorded. The computer name is guaranteed to have been recorded only if the version is a conflict version. This will be different from that computer's current name if the computer's name has been changed since the version was retrieved from that computer. * @return The converted Objective-C result. */ std::string localized_name_of_saving_computer() const; @@ -185,13 +185,13 @@ namespace cocoon PersonNameComponents originator_name_components() const; /** * @brief Returns the `resolved` property of `NSFileVersion`. - * @details A Boolean value that indicates whether the conflict has been resolved. When the system detects a conflict involving versions of a file, it sets this property to NO to indicate an unresolved conflict. After you resolve the conflict, set this property to YES to tell the system it is resolved; you must then remove any versions of the file that are no longer useful. Never set the value of this property to NO. If you do, the system raises an exception. Resolving a conflict causes the file version object to be removed from any reports about conflicting versions, such as those returned by the +unresolvedConflictVersionsOfItemAtURL: method. + * @details If the version is a conflict version, whether the conflict has been resolved. If the version is not a conflict version, simply YES. The operating system's reaction to your setting this to YES is complicated and subject to change in future releases. One result however is that the version won't appear in arrays returned by +unresolvedConflictVersionsOfItemAtURL: anymore, unless setting fails. Once you have indicated that a conflict has been resolved you cannot make it unresolved again. Setting this to NO causes an exception to be thrown. * @return The converted Objective-C result. */ bool is_resolved() const; /** * @brief Sets the `resolved` property of `NSFileVersion`. - * @details A Boolean value that indicates whether the conflict has been resolved. When the system detects a conflict involving versions of a file, it sets this property to NO to indicate an unresolved conflict. After you resolve the conflict, set this property to YES to tell the system it is resolved; you must then remove any versions of the file that are no longer useful. Never set the value of this property to NO. If you do, the system raises an exception. Resolving a conflict causes the file version object to be removed from any reports about conflicting versions, such as those returned by the +unresolvedConflictVersionsOfItemAtURL: method. + * @details If the version is a conflict version, whether the conflict has been resolved. If the version is not a conflict version, simply YES. The operating system's reaction to your setting this to YES is complicated and subject to change in future releases. One result however is that the version won't appear in arrays returned by +unresolvedConflictVersionsOfItemAtURL: anymore, unless setting fails. Once you have indicated that a conflict has been resolved you cannot make it unresolved again. Setting this to NO causes an exception to be thrown. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_resolved(bool value) const; diff --git a/include/generated/file_wrapper.h b/include/generated/file_wrapper.h index 69c22352..5ea33164 100644 --- a/include/generated/file_wrapper.h +++ b/include/generated/file_wrapper.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFileWrapper` (Foundation). - * @details A representation of a node (a file, directory, or symbolic link) in the file system. The ''FileWrapper'' class provides access to the attributes and contents of file system nodes. A file system node is a file, directory, or symbolic link. Instances of this class are known as file wrappers. > Note: > Starting in macOS 10.7, ''FileWrapper'' moved from Application Kit to Foundation. As a result of this the 'icon', and 'setIcon:' methods have moved to a new category of ''FileWrapper'' that remains in Application Kit. File wrappers represent a file system node as an object that can be displayed as an image (and possibly edited in place), saved to the file system, or transmitted to another application. There are three types of file wrappers: - Regular-file file wrapper: Represents a regular file. - Directory file wrapper: Represents a directory. - Symbolic-link file wrapper: Represents a symbolic link. A file wrapper has these attributes: - Filename. Name of the file system node the file wrapper represents. - file-system attributes. See ''FileManager'' for information on the contents of the 'attributes' dictionary. - Regular-file contents. Applicable only to regular-file file wrappers. - File wrappers. Applicable only to directory file wrappers. - Destination node. Applicable only to symbolic-link file wrappers. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -58,14 +57,14 @@ namespace cocoon explicit FileWrapper(Adopt adopt); /** * @brief Calls `-[NSFileWrapper addFileWrapper:]`. - * @details Adds a child file wrapper to the receiver, which must be a directory file wrapper. Use this method to add an existing file wrapper as a child of a directory file wrapper. If the file wrapper does not have a preferred filename, set the 'preferredFilename' property to give it one before calling -addFileWrapper:. To create a new file wrapper and add it to a directory, use the -addRegularFileWithContents:preferredFilename: method. This method raises 'NSInternalInconsistencyException' if the receiver is not a directory file wrapper. This method raises 'NSInvalidArgumentException' if the child file wrapper doesn't have a preferred name. - Parameter child: File wrapper to add to the directory. - Returns: Dictionary key used to store 'fileWrapper' in the directory's list of file wrappers. The dictionary key is a unique filename, which is the same as the passed-in file wrapper's preferred filename unless that name is already in use as a key in the directory's dictionary of children. + * @details Add a file wrapper to the receiver's children and return the file name that uniquely identifies it among the receiver's children. The unique file name will be the same as the passed-in file wrapper's preferred file name unless that name is already in use as a key into the receiver's dictionary of children. Beware of the fact that -initDirectoryWithFileWrappers:, -initRegularFileWithContents:, and -initSymbolicLinkWithDestinationURL: do not automatically set the preferred file name. * @param child Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string add_file_wrapper(const FileWrapper& child) const; /** * @brief Calls `-[NSFileWrapper addRegularFileWithContents:preferredFilename:]`. - * @details Creates a regular-file file wrapper with the given contents and adds it to the receiver, which must be a directory file wrapper. This is a convenience method. The default implementation allocates a new file wrapper, initializes it with -initRegularFileWithContents:, sets its preferred filename, adds it to the directory with -addFileWrapper:, and returns what -addFileWrapper: returned. This method raises 'NSInternalInconsistencyException' if the receiver is not a directory file wrapper. This method raises 'NSInvalidArgumentException' if you pass 'nil' or an empty value for 'filename'. - Parameters: - data: Contents for the new regular-file file wrapper. - fileName: Preferred filename for the new regular-file file wrapper. - Returns: Dictionary key used to store the new file wrapper in the directory's list of file wrappers. The dictionary key is a unique filename, which is the same as the passed-in file wrapper's preferred filename unless that name is already in use as a key in the directory's dictionary of children. + * @details A convenience method. The default implementation merely allocates a new file wrapper, initializes it with -initRegularFileWithContents:, sends it -setPreferredFileName:fileName, adds it to the receiver with -addFileWrapper:, and returns what -addFileWrapper: returned. * @param data Argument converted to the Objective-C parameter of the same role. * @param file_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -73,21 +72,21 @@ namespace cocoon std::string add_regular_file_with_contents(const std::vector& data, const std::string& file_name) const; /** * @brief Calls `-[NSFileWrapper keyForFileWrapper:]`. - * @details Returns the dictionary key used by a directory to identify a given file wrapper. The dictionary key is a unique filename, which may not be the same as the passed-in file wrapper's preferred filename if more than one file wrapper in the directory's dictionary of children has the same preferred filename. Returns 'nil' if the file wrapper specified in 'child' is not a child of the directory. This method raises 'NSInternalInconsistencyException' if the receiver is not a directory file wrapper. - Parameter child: The child file wrapper for which you want the key. - Returns: Dictionary key used to store the file wrapper in the directory's list of file wrappers. + * @details Return the unique file name that has been assigned to a child or nil if it is not a child of the receiver. * @param child Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string key_for_file_wrapper(const FileWrapper& child) const; /** * @brief Calls `-[NSFileWrapper matchesContentsOfURL:]`. - * @details Indicates whether the contents of a file wrapper matches a directory, regular file, or symbolic link on disk. The contents of files are not compared; matching of regular files is based on file modification dates. For a directory, children are compared against the files in the directory, recursively. Because children of directory file wrappers are not read immediately by the -initWithURL:options:error: method unless the NSFileWrapperReadingImmediate reading option is used, even a newly-created directory file wrapper might not have the same contents as the directory on disk. You can use this method to determine whether the file wrapper's contents in memory need to be updated. If the file wrapper needs updating, use the -readFromURL:options:error: method with the NSFileWrapperReadingImmediate reading option. - Parameter url: URL of the file-system node with which to compare the file wrapper. - Returns: 'YES' when the contents of the file wrapper match the contents of 'url', 'NO' otherwise. + * @details Whether the receiver matches the directory, regular file, or symbolic link that is located by the URL. For a directory, children are compared against the files in the directory, recursively. The contents of files are not compared; matching of regular files is based on file modification dates. Because children of directory file wrappers are not read immediately by -initWithURL:options:error: or -readFromURL:options:error: unless NSFileWrapperReadingImmediate is used, creating a file wrapper and then later sending it this message is not a reliable way to simply check whether anything in a directory has changed. You can use this method to determine whether the receiver's contents in memory are out of date relative to the file system. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool matches_contents_of_url(const URL& url) const; /** * @brief Calls `-[NSFileWrapper readFromURL:options:error:]`. - * @details Recursively rereads the entire contents of a file wrapper from the specified location on disk. When reading a directory, children are added and removed as necessary to match the file system. - Parameters: - url: URL of the file-system node corresponding to the file wrapper. - options: Option flags for reading the node located at 'url'. See 'NSFileWrapperReadingOptions' for possible values. - outError: If an error occurs, upon return contains an 'NSError' object that describes the problem. Pass 'NULL' if you do not want error information. - Returns: 'YES' if successful. If not successful, returns 'NO' after setting 'outError' to an 'NSError' object that describes the reason why the file wrapper could not be reread. + * @details Recursively reread the entire contents of the receiver from the specified location, and return YES if successful. If not successful, return NO after setting outError to an NSError that encapsulates the reason why the file wrapper could not be reread. When reading a directory children are added and removed as necessary to match the file system. * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -95,13 +94,13 @@ namespace cocoon bool read_from_url(const URL& url, FileWrapperReadingOptions options) const; /** * @brief Calls `-[NSFileWrapper removeFileWrapper:]`. - * @details Removes a child file wrapper from the receiver, which must be a directory file wrapper. This method raises 'NSInternalInconsistencyException' if the receiver is not a directory file wrapper. - Parameter child: File wrapper to remove from the directory. + * @details Remove a file wrapper from the receiver's children. * @param child Argument converted to the Objective-C parameter of the same role. */ void remove_file_wrapper(const FileWrapper& child) const; /** * @brief Calls `-[NSFileWrapper writeToURL:options:originalContentsURL:error:]`. - * @details Recursively writes the entire contents of a file wrapper to a given file-system URL. - Parameters: - url: URL of the file-system node to which the file wrapper's contents are written. - options: Option flags for writing to the node located at 'url'. See 'NSFileWrapperWritingOptions' for possible values. - originalContentsURL: The location of a previous revision of the contents being written. The default implementation of this method attempts to avoid unnecessary I/O by writing hard links to regular files instead of actually writing out their contents when the contents have not changed. The child file wrappers must return accurate values when sent -filename for this to work. Use the NSFileWrapperWritingWithNameUpdating writing option to increase the likelihood of that. Specify 'nil' for this parameter if there is no earlier version of the contents or if you want to ensure that all the contents are written to files. - outError: If an error occurs, upon return contains an 'NSError' object that describes the problem. Pass 'NULL' if you do not want error information. - Returns: 'YES' when the write operation is successful. If not successful, returns 'NO' after setting 'outError' to an 'NSError' object that describes the reason why the file wrapper's contents could not be written. + * @details Recursively write the entire contents of the receiver at the specified location, and return YES if successful. If not successful, return NO after setting outError to an NSError that encapsulates the reason why the file wrapper could not be written. originalContentsURL may be nil or it may be the location of a previous revision of what is being written. If it is not nil the default implementation of this method attempts to avoid unnecessary I/O by merely writing hard links to regular files instead of actually writing out their contents. The descendant file wrappers must return accurate values when sent -filename for this to work (use NSFileWrapperWritingWithNameUpdating to increase the likelihood of that). * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param original_contents_url Argument converted to the Objective-C parameter of the same role. @@ -110,37 +109,37 @@ namespace cocoon bool write_to_url(const URL& url, FileWrapperWritingOptions options, const URL& original_contents_url) const; /** * @brief Returns the `directory` property of `NSFileWrapper`. - * @details This property contains a boolean value indicating whether the file wrapper is a directory file wrapper. Invocations of -readFromURL:options:error: may change the value of this property, if the type of the file on disk has changed. + * @details What kind of file wrapper it is. Invocations of -readFromURL:options:error: may change what subsequent invocations of these methods return. * @return The converted Objective-C result. */ bool is_directory() const; /** * @brief Returns the `fileAttributes` property of `NSFileWrapper`. - * @details A dictionary of file attributes. The file attributes' dictionary is the same format as that returned by -[NSFileManager attributesOfItemAtPath:error:]. + * @details The file attributes, in a dictionary of the same sort as those returned by -[NSFileManager attributesOfItemAtPath:error:]. * @return The converted Objective-C result. */ std::map file_attributes() const; /** * @brief Sets the `fileAttributes` property of `NSFileWrapper`. - * @details A dictionary of file attributes. The file attributes' dictionary is the same format as that returned by -[NSFileManager attributesOfItemAtPath:error:]. + * @details The file attributes, in a dictionary of the same sort as those returned by -[NSFileManager attributesOfItemAtPath:error:]. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_file_attributes(const std::map& value) const; /** * @brief Returns the `fileWrappers` property of `NSFileWrapper`. - * @details The file wrappers contained by a directory file wrapper. The dictionary contains entries whose values are the file wrappers and whose keys are the unique filenames that have been assigned to each one. This property may contain 'nil' if the user modifies the directory after you call -readFromURL:options:error: or -initWithURL:options:error: but before NSFileWrapper has read the contents of the directory. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem. This property raises 'NSInternalInconsistencyException' if the file wrapper object is not a directory file wrapper. + * @details Return a dictionary whose values are the receiver's children and whose keys are the unique file name that has been assigned to each one. This method may return nil if the receiver is the result of reading a parent from the file system (use NSFileWrapperReadingImmediately if appropriate to prevent that). * @return The converted Objective-C result. */ std::map file_wrappers() const; /** * @brief Returns the `filename` property of `NSFileWrapper`. - * @details The filename of the file wrapper object. This property contains the file wrapper's filename, or 'nil' when the file wrapper has no corresponding file-system node. The filename is used for record-keeping purposes only and is set automatically when the file wrapper is created from the file system using -initWithURL:options:error: and when it's saved to the file system using -writeToURL:options:originalContentsURL:error: (although this method allows you to request that the filename not be updated). The filename is usually the same as the preferred filename, but might instead be a name derived from the preferred filename. You can use this method to get the name of a child that's just been read. Don't use this method to get the name of a child that's about to be written, because the name might be about to change; send -keyForFileWrapper: to the parent instead. + * @details The actual file name. Often it will be the same as the preferred file name but might instead be a name derived from the preferred file name. You can use this method to find out the name of a child that's just been read but you should not use it to find out the name of a child that's about to be written, because the name might be about to change. Send -keyForFileWrapper: to the parent instead. * @return The converted Objective-C result. */ std::string filename() const; /** * @brief Sets the `filename` property of `NSFileWrapper`. - * @details The filename of the file wrapper object. This property contains the file wrapper's filename, or 'nil' when the file wrapper has no corresponding file-system node. The filename is used for record-keeping purposes only and is set automatically when the file wrapper is created from the file system using -initWithURL:options:error: and when it's saved to the file system using -writeToURL:options:originalContentsURL:error: (although this method allows you to request that the filename not be updated). The filename is usually the same as the preferred filename, but might instead be a name derived from the preferred filename. You can use this method to get the name of a child that's just been read. Don't use this method to get the name of a child that's about to be written, because the name might be about to change; send -keyForFileWrapper: to the parent instead. + * @details The actual file name. Often it will be the same as the preferred file name but might instead be a name derived from the preferred file name. You can use this method to find out the name of a child that's just been read but you should not use it to find out the name of a child that's about to be written, because the name might be about to change. Send -keyForFileWrapper: to the parent instead. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_filename(const std::string& value) const; @@ -156,43 +155,41 @@ namespace cocoon void set_icon(const Image& value) const; /** * @brief Returns the `preferredFilename` property of `NSFileWrapper`. - * @details The preferred filename for the file wrapper object. This name is normally used as the dictionary key when a child file wrapper is added to a directory file wrapper. However, if another file wrapper with the same preferred name already exists in the directory file wrapper when this object is added, the filename assigned as the dictionary key may differ from the preferred filename. When you change the preferred filename, the default implementation of this property causes the existing parent directory file wrappers to remove and re-add the child to accommodate the change. Preferred filenames of children are not preserved when you write a file wrapper to disk and then later instantiate another file wrapper by reading the file from disk. If you need to preserve the user-visible names of attachments, you have to store the names yourself. Some instances of NSFileWrapper may be created without a preferredFilename (e.g. -initDirectoryWithFileWrappers: or -initRegularFileWithContents:), meaning preferredFilename may be nil. However, setting nil is never allowed and will result in an exception. + * @details The file name that is "preferred." When the receiver is added to a parent directory file wrapper the parent will attempt to use this name as the key into its dictionary of children. Usually the preferred file name will actually get used in this situation but it won't be if that key is already in use. The default implementation of this method causes existing parents to remove and re-add the child to accommodate the change. Preferred file names of children are not effectively preserved when you write a file wrapper to disk and then later instantiate another file wrapper by reading. If your application needs to preserve the user-visible names of attachments it has to make its own arrangements for their storage. Some instances of NSFileWrapper may be created without a preferredFilename (e.g. -initDirectoryWithFileWrappers: or -initRegularFileWithContents:), meaning preferredFilename may be nil. However, setting nil is never allowed and will result in an exception. * @return The converted Objective-C result. */ std::string preferred_filename() const; /** * @brief Sets the `preferredFilename` property of `NSFileWrapper`. - * @details The preferred filename for the file wrapper object. This name is normally used as the dictionary key when a child file wrapper is added to a directory file wrapper. However, if another file wrapper with the same preferred name already exists in the directory file wrapper when this object is added, the filename assigned as the dictionary key may differ from the preferred filename. When you change the preferred filename, the default implementation of this property causes the existing parent directory file wrappers to remove and re-add the child to accommodate the change. Preferred filenames of children are not preserved when you write a file wrapper to disk and then later instantiate another file wrapper by reading the file from disk. If you need to preserve the user-visible names of attachments, you have to store the names yourself. Some instances of NSFileWrapper may be created without a preferredFilename (e.g. -initDirectoryWithFileWrappers: or -initRegularFileWithContents:), meaning preferredFilename may be nil. However, setting nil is never allowed and will result in an exception. + * @details The file name that is "preferred." When the receiver is added to a parent directory file wrapper the parent will attempt to use this name as the key into its dictionary of children. Usually the preferred file name will actually get used in this situation but it won't be if that key is already in use. The default implementation of this method causes existing parents to remove and re-add the child to accommodate the change. Preferred file names of children are not effectively preserved when you write a file wrapper to disk and then later instantiate another file wrapper by reading. If your application needs to preserve the user-visible names of attachments it has to make its own arrangements for their storage. Some instances of NSFileWrapper may be created without a preferredFilename (e.g. -initDirectoryWithFileWrappers: or -initRegularFileWithContents:), meaning preferredFilename may be nil. However, setting nil is never allowed and will result in an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_preferred_filename(const std::string& value) const; /** * @brief Returns the `regularFile` property of `NSFileWrapper`. - * @details This property contains a boolean value that indicates whether the file wrapper object is a regular-file. Invocations of -readFromURL:options:error: may change the value of this property if the type of the file on disk has changed. * @return The converted Objective-C result. */ bool is_regular_file() const; /** * @brief Returns the `regularFileContents` property of `NSFileWrapper`. - * @details The contents of the file-system node associated with a regular-file file wrapper. This property may contain 'nil' if the user modifies the file after you call -readFromURL:options:error: or -initWithURL:options:error: but before NSFileWrapper has read the contents of the file. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem. This property raises 'NSInternalInconsistencyException' if the file wrapper object is not a regular-file file wrapper. + * @details Return the receiver's contents. This may return nil if the receiver is the result of reading a parent from the file system (use NSFileWrapperReadingImmediately if appropriate to prevent that). * @return The converted Objective-C result. */ std::vector regular_file_contents() const; /** * @brief Returns the `serializedRepresentation` property of `NSFileWrapper`. - * @details The contents of the file wrapper as an opaque data object. This property contains a data object in the format used by the NSFileContentsPboardType pasteboard type. This data object is also suitable for passing to -initWithSerializedRepresentation:. This property may be 'nil' if the user modifies the contents of the file system node after you call -readFromURL:options:error: or -initWithURL:options:error:, but before NSFileWrapper has read the contents of the file. You can use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of this problem. + * @details Return an NSData suitable for passing to -initWithSerializedRepresentation:. This method may return nil if the receiver is the result of reading from the file system (use NSFileWrapperReadingImmediately if appropriate to prevent that). * @return The converted Objective-C result. */ std::vector serialized_representation() const; /** * @brief Returns the `symbolicLink` property of `NSFileWrapper`. - * @details A boolean that indicates whether the file wrapper object is a symbolic-link file wrapper. Invocations of -readFromURL:options:error: may change the value contained by this property, if the type of the file on disk has changed. * @return The converted Objective-C result. */ bool is_symbolic_link() const; /** * @brief Returns the `symbolicLinkDestinationURL` property of `NSFileWrapper`. - * @details The URL referenced by the file wrapper object, which must be a symbolic-link file wrapper. This property may contain 'nil' if the user modifies the symbolic link after you call -readFromURL:options:error: or -initWithURL:options:error: but before NSFileWrapper has read the contents of the link. Use the NSFileWrapperReadingImmediate reading option to reduce the likelihood of that problem. This property raises 'NSInternalInconsistencyException' if the file wrapper object is not a symbolic-link file wrapper. + * @details Return the destination link of the receiver. This may return nil if the receiver is the result of reading a parent from the file system (use NSFileWrapperReadingImmediately if appropriate to prevent that). * @return The converted Objective-C result. */ URL symbolic_link_destination_url() const; diff --git a/include/generated/formatter.h b/include/generated/formatter.h index d00c0ffd..629fe3e8 100644 --- a/include/generated/formatter.h +++ b/include/generated/formatter.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSFormatter` (Foundation). - * @details An abstract class that declares an interface for objects that create, interpret, and validate the textual representation of values. The Foundation framework provides several concrete subclasses of ''Formatter'', including ''ByteCountFormatter'', ''DateFormatter'', ''DateComponentsFormatter'', ''DateIntervalFormatter'', ''MeasurementFormatter'', ''NumberFormatter'', and ''PersonNameComponentsFormatter''. > Tip: > In Swift, you can use implementations of ''FormatStyle'' rather than ''Formatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. \#\#\# Subclassing Notes ''Formatter'' is intended for subclassing. A custom formatter can restrict the input and enhance the display of data in novel ways. For example, you could have a custom formatter that ensures that serial numbers entered by a user conform to predefined formats. Before you decide to create a custom formatter, make sure that you cannot configure the public subclasses to satisfy your requirements. For instructions on how to create your own custom formatter, see [Creating a Custom Formatter](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DataFormatting/Articles/CreatingACustomFormatter.html\#//apple_ref/doc/uid/20000196). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -34,7 +33,6 @@ namespace cocoon explicit Formatter(Adopt adopt); /** * @brief Calls `-[NSFormatter attributedStringForObjectValue:withDefaultAttributes:]`. - * @details Returns an attributed string representation of a given object. * @param obj Argument converted to the Objective-C parameter of the same role. * @param attrs Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -42,14 +40,12 @@ namespace cocoon AttributedString attributed_string_for_object_value(const Object& obj, const std::map& attrs) const; /** * @brief Calls `-[NSFormatter editingStringForObjectValue:]`. - * @details Returns a string to use for editing a given object. * @param obj Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string editing_string_for_object_value(const Object& obj) const; /** * @brief Calls `-[NSFormatter isPartialStringValid:newEditingString:errorDescription:]`. - * @details Returns a Boolean value that indicates whether a partial string is valid. Compatibility method. If a subclass overrides this and does not override the new method below, this will be called as before (the new method just calls this one by default). The selection range will always be set to the end of the text with this method if replacement occurs. * @param partial_string Argument converted to the Objective-C parameter of the same role. * @param new_string Argument converted to the Objective-C parameter of the same role. * @param error Argument converted to the Objective-C parameter of the same role. @@ -58,7 +54,6 @@ namespace cocoon bool is_partial_string_valid(const std::string& partial_string, std::string& new_string, std::string& error) const; /** * @brief Calls `-[NSFormatter isPartialStringValid:proposedSelectedRange:originalString:originalSelectedRange:errorDescription:]`. - * @details This method should be implemented in subclasses that want to validate user changes to a string in a field, where the user changes are not necessarily at the end of the string, and preserve the selection (or set a different one, such as selecting the erroneous part of the string the user has typed). * @param partial_string_ptr Argument converted to the Objective-C parameter of the same role. * @param proposed_sel_range_ptr Argument converted to the Objective-C parameter of the same role. * @param orig_string Argument converted to the Objective-C parameter of the same role. @@ -69,7 +64,6 @@ namespace cocoon bool is_partial_string_valid(std::string& partial_string_ptr, Range* proposed_sel_range_ptr, const std::string& orig_string, const Range& orig_sel_range, std::string& error) const; /** * @brief Calls `-[NSFormatter stringForObjectValue:]`. - * @details Returns a string representation of a given object. * @param obj Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ diff --git a/include/generated/generated.h b/include/generated/generated.h index 7f395b4e..5b414914 100644 --- a/include/generated/generated.h +++ b/include/generated/generated.h @@ -343,7 +343,6 @@ #include "generated/radio_button.h" #include "generated/range_specifier.h" #include "generated/recursive_lock.h" -#include "generated/refresh_controller.h" #include "generated/regular_expression.h" #include "generated/relative_date_time_formatter.h" #include "generated/relative_specifier.h" @@ -420,7 +419,6 @@ #include "generated/status_bar.h" #include "generated/status_bar_button.h" #include "generated/status_item.h" -#include "generated/status_item_expanded_interface_session.h" #include "generated/stepper.h" #include "generated/stepper_cell.h" #include "generated/stepper_touch_bar_item.h" @@ -471,7 +469,6 @@ #include "generated/text_preview.h" #include "generated/text_range.h" #include "generated/text_selection.h" -#include "generated/text_selection_manager.h" #include "generated/text_selection_navigation.h" #include "generated/text_storage.h" #include "generated/text_tab.h" @@ -569,9 +566,6 @@ #include "generated/view.h" #include "generated/view_animation.h" #include "generated/view_controller.h" -#include "generated/view_corner_configuration.h" -#include "generated/view_corner_radii.h" -#include "generated/view_corner_radius.h" #include "generated/view_layout_region.h" #include "generated/visual_effect_view.h" #include "generated/whose_specifier.h" diff --git a/include/generated/gesture_recognizer.h b/include/generated/gesture_recognizer.h index bba00c0b..94dbd128 100644 --- a/include/generated/gesture_recognizer.h +++ b/include/generated/gesture_recognizer.h @@ -33,8 +33,8 @@ namespace cocoon * auto action = gesture_recognizer.action(); * gesture_recognizer.set_allowed_touch_types(cocoon::TouchTypeMask::Direct); * auto allowed_touch_types = gesture_recognizer.allowed_touch_types(); - * gesture_recognizer.set_cancellable_by_scroll_gesture(true); - * auto cancellable_by_scroll_gesture = gesture_recognizer.is_cancellable_by_scroll_gesture(); + * gesture_recognizer.set_delays_key_events(true); + * auto delays_key_events = gesture_recognizer.delays_key_events(); * gesture_recognizer.can_be_prevented_by_gesture_recognizer(cocoon::GestureRecognizer()); * gesture_recognizer.can_prevent_gesture_recognizer(cocoon::GestureRecognizer()); * gesture_recognizer.flags_changed(cocoon::Event()); @@ -81,7 +81,7 @@ namespace cocoon void key_up(const Event& event) const; /** * @brief Calls `-[NSGestureRecognizer locationInView:]`. - * @details individual NSGestureRecognizer subclasses may provide subclass-specific location information. see individual subclasses for details. Note that locationInView: is only set after the recognizer starts recognizing events, so for example it is not valid to consult locationInView: from gestureRecognizer:shouldAttemptToRecognizeWithEvent: or gestureRecognizer:shouldReceiveTouch:, but it is valid for gestureRecognizerShouldBegin: + * @details individual NSGestureRecognizer subclasses may provide subclass-specific location information. see individual subclasses for details * @param view Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -204,34 +204,16 @@ namespace cocoon void set_action(const std::string& value) const; /** * @brief Returns the `allowedTouchTypes` property of `NSGestureRecognizer`. - * @details Currently, only NSTouchTypeDirect is supported. Defaults to NSTouchTypeDirect as of macOS 27, and 0 on earlier releases. + * @details Currently, only NSTouchTypeDirect is supported. Defaults to 0 * @return The converted Objective-C result. */ TouchTypeMask allowed_touch_types() const; /** * @brief Sets the `allowedTouchTypes` property of `NSGestureRecognizer`. - * @details Currently, only NSTouchTypeDirect is supported. Defaults to NSTouchTypeDirect as of macOS 27, and 0 on earlier releases. + * @details Currently, only NSTouchTypeDirect is supported. Defaults to 0 * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allowed_touch_types(TouchTypeMask value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `cancellableByScrollGesture` property of `NSGestureRecognizer`. - * @details Causes the receiver to be cancelled when its enclosing scroll view's gesture recognizer begins. Defaults to 'false'. - * @return The converted Objective-C result. - */ - bool is_cancellable_by_scroll_gesture() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `cancellableByScrollGesture` property of `NSGestureRecognizer`. - * @details Causes the receiver to be cancelled when its enclosing scroll view's gesture recognizer begins. Defaults to 'false'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_cancellable_by_scroll_gesture(bool value) const; -#endif - /** * @brief Returns the `delaysKeyEvents` property of `NSGestureRecognizer`. * @return The converted Objective-C result. diff --git a/include/generated/glass_effect_view.h b/include/generated/glass_effect_view.h index 50d1c4da..e3ac6f65 100644 --- a/include/generated/glass_effect_view.h +++ b/include/generated/glass_effect_view.h @@ -33,8 +33,8 @@ namespace cocoon * auto content_view = glass_effect_view.content_view(); * glass_effect_view.set_corner_radius(1); * auto corner_radius = glass_effect_view.corner_radius(); - * glass_effect_view.set_effect_is_interactive(true); - * auto effect_is_interactive = glass_effect_view.effect_is_interactive(); + * glass_effect_view.set_style(cocoon::GlassStyle::Regular); + * auto style = glass_effect_view.style(); * @endcode * @see https://developer.apple.com/documentation/appkit/nsglasseffectview */ @@ -71,24 +71,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_corner_radius(double value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `effectIsInteractive` property of `NSGlassEffectView`. - * @details Enables interactive glass behavior, which adds a visual response to user interactions. This should be enabled for glass that is used as the background for interactive controls or when used as the container of interactive controls. When 'YES', the glass effect will provide visual feedback when it is interacted with. When 'NO', the glass effect remains static. The default value is 'NO'. - * @return The converted Objective-C result. - */ - bool effect_is_interactive() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `effectIsInteractive` property of `NSGlassEffectView`. - * @details Enables interactive glass behavior, which adds a visual response to user interactions. This should be enabled for glass that is used as the background for interactive controls or when used as the container of interactive controls. When 'YES', the glass effect will provide visual feedback when it is interacted with. When 'NO', the glass effect remains static. The default value is 'NO'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_effect_is_interactive(bool value) const; -#endif - /** * @brief Returns the `style` property of `NSGlassEffectView`. * @details The style of glass this view uses. diff --git a/include/generated/hash_table_base.h b/include/generated/hash_table_base.h index 6dc10cec..5a7a72e7 100644 --- a/include/generated/hash_table_base.h +++ b/include/generated/hash_table_base.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSHashTable` (Foundation). - * @details A collection similar to a set, but with broader range of available memory semantics. The hash table is modeled after ''NSSet'' with the following differences: - It can hold weak references to its members. - Its members may be copied on input or may use pointer identity for equality and hashing. - It can contain arbitrary pointers (its members are not constrained to being objects). You can configure an ''NSHashTable'' instance to operate on arbitrary pointers and not just objects, although typically you are encouraged to use the C function API for void \\ pointers. The object-based API (such as ''add(:)'') will not work for non-object pointers without type-casting. Because of its options, 'NSHashTable' is not a set because it can behave differently (for example, if pointer equality is specified two 'isEqual:' strings will both be entered). When configuring hash tables, note that only the options listed in ''NSHashTableOptions'' guarantee that the rest of the API will work correctly—including copying, archiving, and fast enumeration. While other ''NSPointerFunctions'' options are used for certain configurations, such as to hold arbitrary pointers, not all combinations of the options are valid. With some combinations the hash table may not work correctly, or may not even be initialized correctly. \#\#\# Subclassing Notes 'NSHashTable' is not suitable for subclassing. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref HashTable to supply ObjectType. * @@ -50,120 +49,102 @@ namespace cocoon explicit HashTableBase(Adopt adopt); /** * @brief Calls `-[NSHashTable addObject:]`. - * @details Adds a given object to the hash table. - Parameter object: The object to add to the hash table. * @param object Argument converted to the Objective-C parameter of the same role. */ void add_object(const Object& object) const; /** * @brief Calls `-[NSHashTable containsObject:]`. - * @details Returns a Boolean value that indicates whether the hash table contains a given object. - Parameter anObject: The object to test for membership in the hash table. - Returns: 'YES' if the hash table contains 'anObject', otherwise 'NO'. * @param an_object Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool contains_object(const Object& an_object) const; /** * @brief Calls `+[NSHashTable hashTableWithOptions:]`. - * @details Returns a hash table with given pointer functions options. - Parameter options: A bit field that specifies the options for the elements in the hash table. - Returns: A hash table with given pointer functions options. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static HashTableBase hash_table_with_options(PointerFunctionsOptions options); /** * @brief Calls `-[NSHashTable intersectHashTable:]`. - * @details Removes from the receiving hash table each element that isn't a member of another given hash table. - Parameter other: The hash table with which to perform the intersection. * @param other Argument converted to the Objective-C parameter of the same role. */ void intersect_hash_table(const HashTableBase& other) const; /** * @brief Calls `-[NSHashTable intersectsHashTable:]`. - * @details Returns a Boolean value that indicates whether a given hash table intersects with the receiving hash table. - Parameter other: The hash table with which to compare the receiving hash table. - Returns: 'YES' if 'other' intersects with the receiving hash table, otherwise 'NO'. * @param other Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool intersects_hash_table(const HashTableBase& other) const; /** * @brief Calls `-[NSHashTable isEqualToHashTable:]`. - * @details Returns a Boolean value that indicates whether a given hash table is equal to the receiving hash table. Two hash tables have equal contents if they each have the same number of members and if each member of one hash table is present in the other. - Parameter other: The hash table with which to compare the receiving hash table. - Returns: 'YES' if the contents of 'other' are equal to the contents of the receiving hash table, otherwise 'NO'. * @param other Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equal_to_hash_table(const HashTableBase& other) const; /** * @brief Calls `-[NSHashTable isSubsetOfHashTable:]`. - * @details Returns a Boolean value that indicates whether every element in the receiving hash table is also present in another given hash table. - Parameter other: The hash table with which to compare the receiving hash table. - Returns: 'YES' if every element in the receiving hash table is also present in 'other', otherwise 'NO'. * @param other Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_subset_of_hash_table(const HashTableBase& other) const; /** * @brief Calls `-[NSHashTable member:]`. - * @details Determines whether the hash table contains a given object, and returns that object if it is present. - Parameter object: The object to test for membership in the hash table. - Returns: If 'object' is a member of the hash table, returns 'object', otherwise returns 'nil'. * @param object Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object member(const Object& object) const; /** * @brief Calls `-[NSHashTable minusHashTable:]`. - * @details Removes each element in another given hash table from the receiving hash table, if present. - Parameter other: The hash table of elements to remove from the receiving hash table. * @param other Argument converted to the Objective-C parameter of the same role. */ void minus_hash_table(const HashTableBase& other) const; /** * @brief Calls `-[NSHashTable objectEnumerator]`. - * @details Returns an enumerator object that lets you access each object in the hash table. It is more efficient to use the fast enumeration protocol (see 'NSFastEnumeration'). - Returns: An enumerator object that lets you access each object in the hash table. * @return The converted Objective-C result. */ EnumeratorBase object_enumerator() const; /** * @brief Calls `-[NSHashTable removeAllObjects]`. - * @details Removes all objects from the hash table. */ void remove_all_objects() const; /** * @brief Calls `-[NSHashTable removeObject:]`. - * @details Removes a given object from the hash table. - Parameter object: The object to remove from the hash table. * @param object Argument converted to the Objective-C parameter of the same role. */ void remove_object(const Object& object) const; /** * @brief Calls `-[NSHashTable unionHashTable:]`. - * @details Adds each element in another given hash table to the receiving hash table, if not present. - Parameter other: The hash table of elements to add to the receiving hash table. * @param other Argument converted to the Objective-C parameter of the same role. */ void union_hash_table(const HashTableBase& other) const; /** * @brief Calls `+[NSHashTable weakObjectsHashTable]`. - * @details Returns a new hash table for storing weak references to its contents. * @return The converted Objective-C result. */ static HashTableBase weak_objects_hash_table(); /** * @brief Returns the `allObjects` property of `NSHashTable`. - * @details The hash table's members. * @return The converted Objective-C result. */ std::vector all_objects() const; /** * @brief Returns the `anyObject` property of `NSHashTable`. - * @details One of the objects in the hash table. One of the objects in the hash table, or 'nil' if the hash table contains no objects. The object returned is chosen at the hash table's convenience -- the selection is not guaranteed to be random. * @return The converted Objective-C result. */ Object any_object() const; /** * @brief Returns the `count` property of `NSHashTable`. - * @details The number of elements in the hash table. * @return The converted Objective-C result. */ std::uint64_t count() const; /** * @brief Returns the `pointerFunctions` property of `NSHashTable`. - * @details The pointer functions for the hash table. + * @details return an NSPointerFunctions object reflecting the functions in use. This is a new autoreleased object that can be subsequently modified and/or used directly in the creation of other pointer "collections". * @return The converted Objective-C result. */ PointerFunctions pointer_functions() const; /** * @brief Returns the `setRepresentation` property of `NSHashTable`. - * @details A set that contains the hash table's members. * @return The converted Objective-C result. */ std::vector set_representation() const; diff --git a/include/generated/host.h b/include/generated/host.h index a68c8de7..f48e8409 100644 --- a/include/generated/host.h +++ b/include/generated/host.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSHost` (Foundation). - * @details A representation of an individual host on the network. The ''NSHost'' class provides methods to access the network name and address information for a host. Instances of the ''NSHost'' class represent individual hosts on a network. Use ''NSHost'' objects to get the current host's names and addresses and to look up other hosts by name or by address. To create an ''NSHost'' object, use the ''current()'', ''init(address:)'', or ''init(name:)'' class methods (don't use 'alloc' and 'init'). These methods use available network administration services to discover all names and addresses for the host requested. They don't attempt to contact the host itself, however. This approach avoids untimely delays due to a host being unavailable, but it may result in incomplete information about the host. An ''NSHost'' object contains all of the network addresses and names discovered for a given host by the network administration services. Each ''NSHost'' object may contain several addresses and have more than one name. If an ''NSHost'' object has more than one name, the additional names are variations on the same name, typically the basic host name plus the fully qualified domain name. For example, with a host name '"sales"' in the domain '"anycorp.com"', an ''NSHost'' object can hold both the names '"sales"' and '"sales.anycorp.com"'. ''NSHost'' methods are thread-safe. \@DeprecationSummary { Use Network framework instead; see the deprecation notice in '\'. } + * @details DEPRECATION NOTICE If you’re using 'NSHost' to resolve DNS names so that you can connect to a service, switch to a connect-by-name API, for example, 'nw_connection'. If you have other DNS resolution needs, switch to \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -42,44 +42,37 @@ namespace cocoon explicit Host(Adopt adopt); /** * @brief Calls `+[NSHost currentHost]`. - * @details Returns an ''NSHost'' object representing the host the process is running on. This method executes synchronously. The execution time of this method can be highly variable, depending on the local network configuration, and may block for several seconds if the network is unreachable. To avoid blocking execution on the main thread, you should call this method in an ''Operation'' or Grand Central Dispatch block that executes asynchronously in the background. - Returns: 'NSHost' object for the process's host. * @return The converted Objective-C result. */ static Host current_host(); /** * @brief Calls `-[NSHost isEqualToHost:]`. - * @details Indicates whether the receiver represents the same host as another 'NSHost' object. - Parameters: - aHost: Host to compare the receiver to. - Returns: 'YES' when the receiver and 'aHost' share at least one network address; 'NO' otherwise. * @param a_host Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equal_to_host(const Host& a_host) const; /** * @brief Returns the `address` property of `NSHost`. - * @details One of the addresses associated with the receiver, such as '"192.42.172.1"' or '"fe80::1"'. * @return The converted Objective-C result. */ std::string address() const; /** * @brief Returns the `addresses` property of `NSHost`. - * @details All of the addresses associated with the receiver, including IPv6 and IPv4 addresses. * @return The converted Objective-C result. */ std::vector addresses() const; /** * @brief Returns the `localizedName` property of `NSHost`. - * @details The localized name for the host. This is the name displayed in the Finder sidebar and the Sharing preference panel. This property only returns a value when sent to the ''currentHost'' instance; all other instances currently return 'nil'. This property is key-value observable. * @return The converted Objective-C result. */ std::string localized_name() const; /** * @brief Returns the `name` property of `NSHost`. - * @details One of the hostnames associated with the receiver. Can be either a simple hostname, such as '"sales"', or a fully qualified domain name, such as '"sales.anycorp.com"'. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Returns the `names` property of `NSHost`. - * @details All of the hostnames associated with the receiver. * @return The converted Objective-C result. */ std::vector names() const; diff --git a/include/generated/http_cookie.h b/include/generated/http_cookie.h index 5695818b..072f63b5 100644 --- a/include/generated/http_cookie.h +++ b/include/generated/http_cookie.h @@ -14,7 +14,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSHTTPCookie` (Foundation). - * @details A representation of an HTTP cookie. An ''HTTPCookie'' object is immutable, initialized from a dictionary that contains the attributes of the cookie. This class supports two different cookie versions: - Version 0: The original cookie format defined by Netscape. Most cookies are in this format. - Version 1: The cookie format defined in [RFC 6265](https://tools.ietf.org/html/rfc6265), HTTP State Management Mechanism. + * @details \@class NSHTTPCookie \@abstract NSHTTPCookie represents an http cookie. \@discussion A NSHTTPCookie instance represents a single http cookie. It is an immutable object initialized from a dictionary that contains the various cookie attributes. It has accessors to get the various attributes of a cookie. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -38,14 +38,14 @@ namespace cocoon explicit HTTPCookie(Adopt adopt); /** * @brief Calls `+[NSHTTPCookie cookieWithProperties:]`. - * @details Allocates and initializes an 'NSHTTPCookie' with the given dictionary. - Parameter properties: The dictionary to use to initialize this cookie. - Returns: A newly-created and autoreleased 'NSHTTPCookie' instance, or 'nil' if the set of dictionary keys is invalid, for example because a required key is missing, or a recognized key maps to an illegal value. See the 'NSHTTPCookie' '-initWithProperties:' method for more information on the constraints imposed on the dictionary, and for descriptions of the supported keys and values. + * @details \@method cookieWithProperties: \@abstract Allocates and initializes an NSHTTPCookie with the given dictionary. \@discussion See the NSHTTPCookie \-initWithProperties:\ method for more information on the constraints imposed on the dictionary, and for descriptions of the supported keys and values. \@param properties The dictionary to use to initialize this cookie. \@result A newly-created and autoreleased NSHTTPCookie instance, or nil if the set of dictionary keys is invalid, for example because a required key is missing, or a recognized key maps to an illegal value. * @param properties Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static HTTPCookie cookie_with_properties(const std::map& properties); /** * @brief Calls `+[NSHTTPCookie cookiesWithResponseHeaderFields:forURL:]`. - * @details Creates an array of HTTP cookies that corresponds to the provided response header fields for the provided URL. - Parameter headerFields: The response header fields to check for cookies. - Parameter URL: The URL that the cookies came from, relevant to how the cookies are interpreted. - Returns: An 'NSArray' of 'NSHTTPCookie' objects. This method ignores irrelevant header fields in 'headerFields', allowing dictionaries to contain additional data. + * @details \@method cookiesWithResponseHeaderFields:forURL: \@abstract Return an array of cookies parsed from the specified response header fields and URL. \@param headerFields The response header fields to check for cookies. \@param URL The URL that the cookies came from - relevant to how the cookies are interpreted. \@result An NSArray of NSHTTPCookie objects \@discussion This method will ignore irrelevant header fields so you can pass a dictionary containing data other than cookie data. * @param header_fields Argument converted to the Objective-C parameter of the same role. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -53,92 +53,92 @@ namespace cocoon static std::vector cookies_with_response_header_fields(const std::map& header_fields, const URL& url); /** * @brief Calls `+[NSHTTPCookie requestHeaderFieldsWithCookies:]`. - * @details Converts an array of cookies to a dictionary of header fields. - Parameter cookies: The cookies from which the header fields are created. - Returns: An 'NSDictionary' where the keys are header field names, and the values are the corresponding header field values. + * @details \@method requestHeaderFieldsWithCookies: \@abstract Return a dictionary of header fields that can be used to add the specified cookies to the request. \@param cookies The cookies to turn into request headers. \@result An NSDictionary where the keys are header field names, and the values are the corresponding header field values. * @param cookies Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::map request_header_fields_with_cookies(const std::vector& cookies); /** * @brief Returns the `HTTPOnly` property of `NSHTTPCookie`. - * @details A Boolean value that indicates whether the cookie should only be sent to HTTP servers. Cookies can be marked as HTTP-only by a server (or by JavaScript code). Cookies marked as such must only be sent via HTTP Headers in HTTP requests for URLs that match both the path and domain of the respective cookies. > Important: To prevent cross-site scripting vulnerabilities, don't deliver cookies marked as HTTP-only to JavaScript code. + * @details \@abstract Returns whether the receiver should only be sent to HTTP servers per RFC 2965 \@discussion Cookies may be marked as HTTPOnly by a server (or by a javascript). Cookies marked as such must only be sent via HTTP Headers in HTTP Requests for URL's that match both the path and domain of the respective Cookies. Specifically these cookies should not be delivered to any javascript applications to prevent cross-site scripting vulnerabilities. \@result YES if this cookie should only be sent via HTTP headers, NO otherwise. * @return The converted Objective-C result. */ bool is_http_only() const; /** * @brief Returns the `comment` property of `NSHTTPCookie`. - * @details The cookie's comment string. This value is 'nil' if the cookie has no comment. You can present this string to the user, explaining the contents and purpose of this cookie. + * @details \@abstract Returns the comment of the receiver. \@discussion This value specifies a string which is suitable for presentation to the user explaining the contents and purpose of this cookie. It may be nil. \@result The comment of the receiver, or nil if the receiver has no comment. * @return The converted Objective-C result. */ std::string comment() const; /** * @brief Returns the `commentURL` property of `NSHTTPCookie`. - * @details The cookie's comment URL. This value is 'nil' if the cookie has no comment URL. This value specifies a URL that can be presented to the user as a link for further information about this cookie. + * @details \@abstract Returns the comment URL of the receiver. \@discussion This value specifies a URL which is suitable for presentation to the user as a link for further information about this cookie. It may be nil. \@result The comment URL of the receiver, or nil if the receiver has no comment URL. * @return The converted Objective-C result. */ URL comment_url() const; /** * @brief Returns the `domain` property of `NSHTTPCookie`. - * @details The domain of the cookie. If the domain does not start with a dot, then the cookie is only sent to the exact host specified by the domain. If the domain does start with a dot, then the cookie is sent to other hosts in that domain as well, subject to certain restrictions. See RFC 6265 for more detail. + * @details \@abstract Returns the domain of the receiver. \@discussion This value specifies URL domain to which the cookie should be sent. A domain with a leading dot means the cookie should be sent to subdomains as well, assuming certain other restrictions are valid. See RFC 2965 for more detail. \@result The domain of the receiver. * @return The converted Objective-C result. */ std::string domain() const; /** * @brief Returns the `expiresDate` property of `NSHTTPCookie`. - * @details The cookie's expiration date. This value is 'nil' if there is no specific expiration date, as with session-only cookies. The expiration date is the date when the cookie should be deleted. + * @details \@abstract Returns the expires date of the receiver. \@result the expires date of the receiver. \@discussion The expires date is the date when the cookie should be deleted. The result will be nil if there is no specific expires date. This will be the case only for "session-only" cookies. \@result The expires date of the receiver. * @return The converted Objective-C result. */ Date expires_date() const; /** * @brief Returns the `name` property of `NSHTTPCookie`. - * @details The cookie's name. + * @details \@abstract Returns the name of the receiver. \@result the name of the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Returns the `path` property of `NSHTTPCookie`. - * @details The cookie's path. The cookie will be sent with requests for this path in the cookie's domain, and all paths that have this prefix. A path of '"/"' means the cookie will be sent for all URLs in the domain. + * @details \@abstract Returns the path of the receiver. \@discussion This value specifies the URL path under the cookie's domain for which this cookie should be sent. The cookie will also be sent for children of that path, so "/" is the most general. \@result The path of the receiver. * @return The converted Objective-C result. */ std::string path() const; /** * @brief Returns the `portList` property of `NSHTTPCookie`. - * @details The cookie's port list. The list of ports for the cookie, returned as an array of 'NSNumber' objects containing integers. If the cookie has no port list, the value of this property is 'nil' and the cookie will be sent to any port. Otherwise, the cookie is only sent to ports specified in the port list. + * @details \@abstract Returns the list ports to which the receiver should be sent. \@discussion This value specifies an NSArray of NSNumbers (containing integers) which specify the only ports to which this cookie should be sent. \@result The list ports to which the receiver should be sent. The array may be nil, in which case this cookie can be sent to any port. * @return The converted Objective-C result. */ std::vector port_list() const; /** * @brief Returns the `properties` property of `NSHTTPCookie`. - * @details The cookie's properties. This dictionary can be used with '-initWithProperties:' or '+cookieWithProperties:' to create an equivalent 'NSHTTPCookie' object. + * @details \@abstract Returns a dictionary representation of the receiver. \@discussion This method returns a dictionary representation of the NSHTTPCookie which can be saved and passed to \-initWithProperties:\ or \+cookieWithProperties:\ later to reconstitute an equivalent cookie. \

See the NSHTTPCookie \-initWithProperties:\ method for more information on the constraints imposed on the dictionary, and for descriptions of the supported keys and values. \@result The dictionary representation of the receiver. * @return The converted Objective-C result. */ std::map properties() const; /** * @brief Returns the `sameSitePolicy` property of `NSHTTPCookie`. - * @details A Boolean value that indicates whether to restrict the cookie to requests sent back to the same site that created it. Cookies can be marked with an attribute Strict or Lax. Cookies marked with "strict" ('NSHTTPCookieSameSiteStrict') are not sent along with cross-site requests. Cookies marked with "lax" ('NSHTTPCookieSameSiteLax') are sent along cross-site requests provided the cross-site requests are top-level requests (one that changes the URL in the address bar). The result could also be 'nil', in which case the cookie will be sent along with all cross-site requests. + * @details \@abstract Returns the value of the same site attribute on the cookie. \@discussion Cookies can be marked with an attribute Strict or Lax. Cookies marked with "strict" (NSHTTPCookieSameSiteStrict) are not sent along with cross-site requests. Cookies marked with "lax" (NSHTTPCookieSameSiteLax) sent along cross-site requests provided the cross-site requests are top-level-requests (one that changes the url in the address bar). The attribute value is canonicalized and stored. Any value other than the default (strict and lax) will be ignored. \@result strict or lax. The result could also be nil, in which case the cookie will be sent along with all cross-site requests. * @return The converted Objective-C result. */ std::string same_site_policy() const; /** * @brief Returns the `secure` property of `NSHTTPCookie`. - * @details A Boolean value that indicates whether the cookie may only be sent over secure channels. Cookies may be marked secure by a server (or by a javascript). Cookies marked as such must only be sent via an encrypted connection to trusted servers (i.e. via SSL or TLS), and should not be delivered to any javascript applications to prevent cross-site scripting vulnerabilities. + * @details \@abstract Returns whether the receiver should be sent only over secure channels \@discussion Cookies may be marked secure by a server (or by a javascript). Cookies marked as such must only be sent via an encrypted connection to trusted servers (i.e. via SSL or TLS), and should not be delivered to any javascript applications to prevent cross-site scripting vulnerabilities. \@result YES if this cookie should be sent only over secure channels, NO otherwise. * @return The converted Objective-C result. */ bool is_secure() const; /** * @brief Returns the `sessionOnly` property of `NSHTTPCookie`. - * @details A Boolean value that indicates whether the cookie should be discarded at the end of the session (regardless of expiration date). + * @details \@abstract Returns whether the receiver is session-only. \@result YES if this receiver should be discarded at the end of the session (regardless of expiration date), NO if receiver need not be discarded at the end of the session. * @return The converted Objective-C result. */ bool is_session_only() const; /** * @brief Returns the `value` property of `NSHTTPCookie`. - * @details The cookie's string value. + * @details \@abstract Returns the value of the receiver. \@result the value of the receiver. * @return The converted Objective-C result. */ std::string value() const; /** * @brief Returns the `version` property of `NSHTTPCookie`. - * @details The cookie's version. Version 0 maps to "old-style" Netscape cookies. Version 1 maps to RFC 2965 cookies. There may be future versions. + * @details \@abstract Returns the version of the receiver. \@discussion Version 0 maps to "old-style" Netscape cookies. Version 1 maps to RFC2965 cookies. There may be future versions. \@result the version of the receiver. * @return The converted Objective-C result. */ std::uint64_t version() const; diff --git a/include/generated/http_cookie_storage.h b/include/generated/http_cookie_storage.h index 2a4b636f..d18428e0 100644 --- a/include/generated/http_cookie_storage.h +++ b/include/generated/http_cookie_storage.h @@ -16,7 +16,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSHTTPCookieStorage` (Foundation). - * @details A container that manages the storage of cookies. Each stored cookie is represented by an instance of the ''HTTPCookie'' class. \#\#\# Sharing cookie storage The persistent cookie storage returned by ''shared'' may be available to app extensions or other apps, subject to the following guidelines: - iOS — Each app and app extension has a unique data container, meaning they have separate cookie stores. You can obtain a common cookie storage by using the ''sharedCookieStorage(forGroupContainerIdentifier:)'' method. - macOS (non-sandboxed) — As of macOS 10.11, each app has its own cookie storage. Prior to macOS 10.11, a common cookie store is shared among the user's apps. - macOS (sandboxed) — Same as iOS. - \ — 'UIWebView' instances within an app inherit the parent app's shared cookie storage. - \ — Each 'WKWebView' instance has its own cookie storage. See the \ class for more information. Session cookies (where the cookie object's ''HTTPCookie/isSessionOnly'' property is \) are local to a single process and are not shared. > Note: > In cases where a cookie storage is shared between processes, changes made to the cookie accept policy affect all currently running apps using the cookie storage. \#\#\# Subclassing notes The ''HTTPCookieStorage'' class is usable as-is, but you can subclass it. For example, you can override the storage methods like ''storeCookies(:for:)'', ''getCookiesFor(:completionHandler:)'' to screen which cookies are stored, or reimplement the storage mechanism for security or other reasons. When overriding methods of this class, be aware that methods that take a 'task' parameter are preferred by the system to equivalent methods that do not. Therefore, you should override the task-based methods when subclassing, as follows: - Retrieving cookies — Override ''getCookiesFor(:completionHandler:)'', instead of or in addition to ''cookies(for:)''. - Adding cookies — Override ''storeCookies(:for:)'', instead of or in addition to ''setCookies(:for:mainDocumentURL:)''. + * @details \@class NSHTTPCookieStorage \@discussion NSHTTPCookieStorage implements a singleton object (shared instance) which manages the shared cookie store. It has methods to allow clients to set and remove cookies, and get the current set of cookies. It also has convenience methods to parse and generate cookie-related HTTP header fields. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -51,39 +51,38 @@ namespace cocoon explicit HTTPCookieStorage(Adopt adopt); /** * @brief Calls `-[NSHTTPCookieStorage cookiesForURL:]`. - * @details Returns all the cookie storage's cookies that are sent to a specified URL. - Parameter URL: The URL to filter on. - Returns: An array of cookies whose URL matches the provided URL. You can use '+[NSHTTPCookie requestHeaderFieldsWithCookies:]' to turn this array into a set of header fields to add to a request. + * @details \@method cookiesForURL: \@abstract Returns an array of cookies to send to the given URL. \@param URL The URL for which to get cookies. \@result an NSArray of NSHTTPCookie objects. \@discussion The cookie manager examines the cookies it stores and includes those which should be sent to the given URL. You can use \+[NSCookie requestHeaderFieldsWithCookies:]\ to turn this array into a set of header fields to add to a request. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector cookies_for_url(const URL& url) const; /** * @brief Calls `-[NSHTTPCookieStorage deleteCookie:]`. - * @details Deletes the specified cookie from the cookie storage. + * @details \@method deleteCookie: \@abstract Delete the specified cookie * @param cookie Argument converted to the Objective-C parameter of the same role. */ void delete_cookie(const HTTPCookie& cookie) const; /** * @brief Calls `-[NSHTTPCookieStorage getCookiesForTask:completionHandler:]`. - * @details Fetches cookies relevant to the specified task and passes them to the completion handler. * @param task Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void get_cookies_for_task(const URLSessionTask& task, std::function)> completion_handler) const; /** * @brief Calls `-[NSHTTPCookieStorage removeCookiesSinceDate:]`. - * @details Removes cookies that were stored after a given date. + * @details \@method removeCookiesSince: \@abstract Delete all cookies from the cookie storage since the provided date. * @param date Argument converted to the Objective-C parameter of the same role. */ void remove_cookies_since_date(const Date& date) const; /** * @brief Calls `-[NSHTTPCookieStorage setCookie:]`. - * @details Stores a specified cookie in the cookie storage if the cookie accept policy permits. The cookie replaces an existing cookie with the same name, domain, and path, if one exists. + * @details \@method setCookie: \@abstract Set a cookie \@discussion The cookie will override an existing cookie with the same name, domain and path, if any. * @param cookie Argument converted to the Objective-C parameter of the same role. */ void set_cookie(const HTTPCookie& cookie) const; /** * @brief Calls `-[NSHTTPCookieStorage setCookies:forURL:mainDocumentURL:]`. - * @details Adds an array of cookies to the cookie store, following the cookie accept policy. - Parameter cookies: The cookies to set. - Parameter URL: The URL from which the cookies were sent. - Parameter mainDocumentURL: The main document URL to be used as a base for the "same domain as main document" policy. For 'mainDocumentURL', the caller should pass the URL for an appropriate main document, if known. For example, when loading a web page, the URL of the main html document for the top-level frame should be passed. To save cookies based on a set of response headers, you can use '+[NSHTTPCookie cookiesWithResponseHeaderFields:forURL:]' on a header field dictionary and then use this method to store the resulting cookies in accordance with policy settings. + * @details \@method setCookies:forURL:mainDocumentURL: \@abstract Adds an array cookies to the cookie store, following the cookie accept policy. \@param cookies The cookies to set. \@param URL The URL from which the cookies were sent. \@param mainDocumentURL The main document URL to be used as a base for the "same domain as main document" policy. \@discussion For mainDocumentURL, the caller should pass the URL for an appropriate main document, if known. For example, when loading a web page, the URL of the main html document for the top-level frame should be passed. To save cookies based on a set of response headers, you can use \+[NSCookie cookiesWithResponseHeaderFields:forURL:]\ on a header field dictionary and then use this method to store the resulting cookies in accordance with policy settings. * @param cookies Argument converted to the Objective-C parameter of the same role. * @param url Argument converted to the Objective-C parameter of the same role. * @param main_document_url Argument converted to the Objective-C parameter of the same role. @@ -91,46 +90,45 @@ namespace cocoon void set_cookies(const std::vector& cookies, const URL& url, const URL& main_document_url) const; /** * @brief Calls `+[NSHTTPCookieStorage sharedCookieStorageForGroupContainerIdentifier:]`. - * @details Returns the cookie storage instance for the container associated with the specified app group identifier. - Parameter identifier: The application group identifier. - Returns: A cookie storage with a persistent store in the application group container. By default, apps and associated app extensions will have different data containers. As a result, the 'sharedHTTPCookieStorage' singleton will refer to different persistent cookie stores when called by the app and by its extensions. You can use this method to create a persistent cookie storage available to all apps and extensions with access to the same app group. Subsequent calls to this method with the same identifier will return the same cookie storage instance. + * @details \@method sharedCookieStorageForGroupContainerIdentifier: \@abstract Get the cookie storage for the container associated with the specified application group identifier \@param identifier The application group identifier \@result A cookie storage with a persistent store in the application group container \@discussion By default, applications and associated app extensions have different data containers, which means that the sharedHTTPCookieStorage singleton will refer to different persistent cookie stores in an application and any app extensions that it contains. This method allows clients to create a persistent cookie storage that can be shared among all applications and extensions with access to the same application group. Subsequent calls to this method with the same identifier will return the same cookie storage instance. * @param identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static HTTPCookieStorage shared_cookie_storage_for_group_container_identifier(const std::string& identifier); /** * @brief Calls `-[NSHTTPCookieStorage sortedCookiesUsingDescriptors:]`. - * @details Returns all of the cookie storage's cookies, sorted according to a given set of sort descriptors. - Parameter sortOrder: An array of 'NSSortDescriptor' objects which represent the preferred sort order of the resulting array. - Returns: The sorted array of cookies. Proper sorting of cookies may require extensive string conversion, which can be avoided by allowing the system to perform the sorting. This API is to be preferred over the more generic 'cookies' property, if sorting is going to be performed. + * @details \@method sortedCookiesUsingDescriptors: \@abstract Returns an array of all cookies in the store, sorted according to the key value and sorting direction of the NSSortDescriptors specified in the parameter. \@param sortOrder an array of NSSortDescriptors which represent the preferred sort order of the resulting array. \@discussion proper sorting of cookies may require extensive string conversion, which can be avoided by allowing the system to perform the sorting. This API is to be preferred over the more generic -[NSHTTPCookieStorage cookies] API, if sorting is going to be performed. * @param sort_order Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector sorted_cookies_using_descriptors(const std::vector& sort_order) const; /** * @brief Calls `-[NSHTTPCookieStorage storeCookies:forTask:]`. - * @details Stores an array of cookies in the cookie storage, on behalf of the provided task, if the cookie accept policy permits. * @param cookies Argument converted to the Objective-C parameter of the same role. * @param task Argument converted to the Objective-C parameter of the same role. */ void store_cookies(const std::vector& cookies, const URLSessionTask& task) const; /** * @brief Returns the `cookieAcceptPolicy` property of `NSHTTPCookieStorage`. - * @details The cookie accept policy preference of the receiver. The default cookie accept policy is 'NSHTTPCookieAcceptPolicyAlways'. + * @details \@abstract The cookie accept policy preference of the receiver. * @return The converted Objective-C result. */ HTTPCookieAcceptPolicy cookie_accept_policy() const; /** * @brief Sets the `cookieAcceptPolicy` property of `NSHTTPCookieStorage`. - * @details The cookie accept policy preference of the receiver. The default cookie accept policy is 'NSHTTPCookieAcceptPolicyAlways'. + * @details \@abstract The cookie accept policy preference of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_cookie_accept_policy(HTTPCookieAcceptPolicy value) const; /** * @brief Returns the `cookies` property of `NSHTTPCookieStorage`. - * @details The cookie storage's cookies. If you want to sort the cookie storage's cookies, you should use the 'sortedCookiesUsingDescriptors:' method instead of sorting the result of this property. + * @details \@abstract Get all the cookies \@result An NSArray of NSHTTPCookies * @return The converted Objective-C result. */ std::vector cookies() const; /** * @brief Returns the `sharedHTTPCookieStorage` property of `NSHTTPCookieStorage`. - * @details The shared cookie storage instance. Starting in OS X 10.11, each app has its own 'sharedHTTPCookieStorage' singleton, which will not be shared with other applications. + * @details \@property sharedHTTPCookieStorage \@abstract Get the shared cookie storage in the default location. \@result The shared cookie storage \@discussion Starting in OS X 10.11, each app has its own sharedHTTPCookieStorage singleton, which will not be shared with other applications. * @return The converted Objective-C result. */ static HTTPCookieStorage shared_http_cookie_storage(); diff --git a/include/generated/httpurl_response.h b/include/generated/httpurl_response.h index 139bc249..ccc99dd8 100644 --- a/include/generated/httpurl_response.h +++ b/include/generated/httpurl_response.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSHTTPURLResponse` (Foundation). - * @details The metadata associated with the response to an HTTP protocol URL load request. The ''HTTPURLResponse'' class is a subclass of ''URLResponse'' that provides methods for accessing information specific to HTTP protocol responses. Whenever you make HTTP URL load requests, any response objects you get back from the ''URLSession'', ''NSURLConnection'', or ''NSURLDownload'' class are instances of the ''HTTPURLResponse'' class. + * @details \@class NSHTTPURLResponse \@abstract An NSHTTPURLResponse object represents a response to an HTTP URL load. It is a specialization of NSURLResponse which provides conveniences for accessing information specific to HTTP protocol responses. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref URLResponse. * @@ -44,27 +44,27 @@ namespace cocoon explicit HTTPURLResponse(Adopt adopt); /** * @brief Calls `+[NSHTTPURLResponse localizedStringForStatusCode:]`. - * @details Returns a localized string corresponding to a specified HTTP status code. - Parameter statusCode: The HTTP status code. See [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt) for details. - Returns: A localized string suitable for displaying to users that describes the specified status code. + * @details \@method localizedStringForStatusCode: \@abstract Convenience method which returns a localized string corresponding to the status code for this response. \@param statusCode the status code to use to produce a localized string. \@result A localized string corresponding to the given status code. * @param status_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string localized_string_for_status_code(std::int64_t status_code); /** * @brief Calls `-[NSHTTPURLResponse valueForHTTPHeaderField:]`. - * @details Returns the value that corresponds to the given header field. In keeping with the HTTP RFC, HTTP header field names are case-insensitive. - Parameter field: The header field name to use for the lookup (case-insensitive). - Returns: The value associated with the given header field, or 'nil' if there is no value associated with the given header field. + * @details \@method valueForHTTPHeaderField: \@abstract Returns the value which corresponds to the given header field. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive. \@param field the header field name to use for the lookup (case-insensitive). \@result the value associated with the given header field, or nil if there is no value associated with the given header field. * @param field Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string value_for_http_header_field(const std::string& field) const; /** * @brief Returns the `allHeaderFields` property of `NSHTTPURLResponse`. - * @details All HTTP header fields of the response. The value of this property is a dictionary that contains all the HTTP header fields received as part of the server's response. By examining this dictionary, clients can see the "raw" header information returned by the HTTP server. HTTP headers are case insensitive. To simplify your code, URL Loading System canonicalizes certain header field names into their standard form. For example, if the server sends a 'content-length' header, it's automatically adjusted to be 'Content-Length'. When using Swift, this property is a standard dictionary, so its keys are case-sensitive. To perform a case-insensitive header lookup, use the 'valueForHTTPHeaderField:' method instead. + * @details \@abstract Returns a dictionary containing all the HTTP header fields of the receiver. \@discussion By examining this header dictionary, clients can see the "raw" header information which was reported to the protocol implementation by the HTTP server. This may be of use to sophisticated or special-purpose HTTP clients. \@result A dictionary containing all the HTTP header fields of the receiver. * @return The converted Objective-C result. */ std::vector> all_header_fields() const; /** * @brief Returns the `statusCode` property of `NSHTTPURLResponse`. - * @details The response's HTTP status code. See [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt) for details. + * @details \@abstract Returns the HTTP status code of the receiver. \@result The HTTP status code of the receiver. * @return The converted Objective-C result. */ std::int64_t status_code() const; diff --git a/include/generated/index_path.h b/include/generated/index_path.h index e5f87ea8..4259b935 100644 --- a/include/generated/index_path.h +++ b/include/generated/index_path.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSIndexPath` (Foundation). - * @details A list of indexes that together represent the path to a specific location in a tree of nested arrays. In Swift, this object bridges to ''IndexPath''; use ''NSIndexPath'' when you need reference semantics or other Foundation-specific behavior. Each index in an index path represents the index into an array of children from one node in the tree to another, deeper, node. For example, the index path '1.4.3.2' specifies the path shown in [Figure 1](/documentation/foundation/nsindexpath\#1965825). ![Index path “1.4.3.2”](media-1965825) > Note: > The UIKit framework adds programming interfaces to the 'NSIndexPath' class of the Foundation framework to facilitate the identification of rows and sections in \ objects and the identification of items and sections in \ objects. The API consists of class factory methods and properties for accessing the various indexed values. You use the factory methods to create an index path for the corresponding table view or collection view. > Important: > The Swift overlay to the Foundation framework provides the ''IndexPath'' structure, which bridges to the ''NSIndexPath'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -46,41 +45,37 @@ namespace cocoon explicit IndexPath(Adopt adopt); /** * @brief Calls `-[NSIndexPath compare:]`. - * @details Indicates the depth-first traversal order of the receiving index path and another index path. - Parameter otherObject: Index path to compare. This value must not be 'nil'. If the value is 'nil', the behavior is undefined. - Returns: The depth-first traversal ordering of the receiving index path and 'otherObject'. * @param other_object Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ComparisonResult compare(const IndexPath& other_object) const; /** * @brief Calls `-[NSIndexPath getIndexes:]`. - * @details Copies the objects contained in the index path into indexes. This method is unsafe because it could potentially cause buffer overruns. You should use 'getIndexes:range:' instead. You must allocate the memory for the C array. - Parameter indexes: Pointer to a C array of objects of size at least the length of the index path. On return, the index path's indexes. + * @details This method is unsafe because it could potentially cause buffer overruns. You should use -getIndexes:range: instead. * @param indexes Argument converted to the Objective-C parameter of the same role. */ void get_indexes(std::uint64_t* indexes) const; /** * @brief Calls `-[NSIndexPath getIndexes:range:]`. - * @details Copies the indexes stored in the index path from the positions specified by the position range into the specified indexes. It is the developer’s responsibility to allocate the memory for the C array. - Parameters: - indexes: Buffer of at least as many 'NSUInteger' values as specified by the length of 'positionRange'. On return, this memory will hold the index path’s indexes. - positionRange: A range of valid positions within this index path. If the location plus the length of 'positionRange' is greater than the length of this index path, this method raises an 'NSRangeException'. + * @details \@abstract Copies the indexes stored in this index path from the positions specified by positionRange into indexes. \@param indexes Buffer of at least as many NSUIntegers as specified by the length of positionRange. On return, this memory will hold the index path's indexes. \@param positionRange A range of valid positions within this index path. If the location plus the length of positionRange is greater than the length of this index path, this method raises an NSRangeException. \@discussion It is the developer’s responsibility to allocate the memory for the C array. * @param indexes Argument converted to the Objective-C parameter of the same role. * @param position_range Argument converted to the Objective-C parameter of the same role. */ void get_indexes(std::uint64_t* indexes, const Range& position_range) const; /** * @brief Calls `-[NSIndexPath indexAtPosition:]`. - * @details Provides the value at a particular node in the index path. - Parameter position: Index value of the desired node. Node numbering starts at zero. - Returns: The index value at 'position' or 'NSNotFound' if the node is outside the range of the index path. * @param position Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t index_at_position(std::uint64_t position) const; /** * @brief Calls `-[NSIndexPath indexPathByAddingIndex:]`. - * @details Returns an index path containing the nodes in the receiving index path plus another given index. - Parameter index: Index to append to the index path's indexes. - Returns: A new index path containing the receiving index path's indexes and 'index'. * @param index Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ IndexPath index_path_by_adding_index(std::uint64_t index) const; /** * @brief Calls `-[NSIndexPath indexPathByRemovingLastIndex]`. - * @details Returns an index path with the nodes in the receiving index path, excluding the last one. Returns an empty 'NSIndexPath' instance if the receiving index path's length is 1 or less. - Returns: A new index path with the receiving index path's indexes, excluding the last one. * @return The converted Objective-C result. */ IndexPath index_path_by_removing_last_index() const; @@ -98,7 +93,6 @@ namespace cocoon std::int64_t item() const; /** * @brief Returns the `length` property of `NSIndexPath`. - * @details The number of nodes in the index path. * @return The converted Objective-C result. */ std::uint64_t length() const; diff --git a/include/generated/index_set.h b/include/generated/index_set.h index fe647af7..f21dec92 100644 --- a/include/generated/index_set.h +++ b/include/generated/index_set.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSIndexSet` (Foundation). - * @details An immutable collection of unique integer values that represent indexes in another collection. In Swift, this type bridges to ''IndexSet''; use ''NSIndexSet'' when you need reference semantics or other Foundation-specific behavior. The 'NSIndexSet' class represents an immutable collection of unique unsigned integers, known as indexes because of the way they are used. This collection is referred to as an index set. Indexes must be in the range '0 .. NSNotFound - 1'. You use index sets in your code to store indexes into some other data structure. For example, given an 'NSArray' object, you could use an index set to identify a subset of objects in that array. You should not use index sets to store an arbitrary collection of integer values because index sets store indexes as sorted ranges. This makes them more efficient than storing a collection of individual integers. It also means that each index value can only appear once in the index set. The designated initializers of the 'NSIndexSet' class are: ''init(index:)'', ''init(indexesIn:)'', and ''init(indexSet:)''. You must not subclass the 'NSIndexSet' class. The mutable subclass of 'NSIndexSet' is ''NSMutableIndexSet''. > Important: > The Swift overlay to the Foundation framework provides the ''IndexSet'' structure, which bridges to the ''NSIndexSet'' class and its mutable subclass, ''NSMutableIndexSet''. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,35 +44,30 @@ namespace cocoon explicit IndexSet(Adopt adopt); /** * @brief Calls `-[NSIndexSet containsIndex:]`. - * @details Indicates whether the index set contains a specific index. - Parameter value: Index being inquired about. - Returns: 'YES' when the index set contains 'index', 'NO' otherwise. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool contains_index(std::uint64_t value) const; /** * @brief Calls `-[NSIndexSet containsIndexes:]`. - * @details Indicates whether the receiving index set contains a superset of the indexes in another index set. - Parameter indexSet: Index set being inquired about. - Returns: 'YES' when the receiving index set contains a superset of the indexes in 'indexSet', 'NO' otherwise. * @param index_set Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool contains_indexes(const IndexSet& index_set) const; /** * @brief Calls `-[NSIndexSet containsIndexesInRange:]`. - * @details Indicates whether the index set contains the indexes represented by an index range. - Parameter range: The index range being inquired about. - Returns: 'YES' when the index set contains the indexes in 'indexRange', 'NO' otherwise. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool contains_indexes_in_range(const Range& range) const; /** * @brief Calls `-[NSIndexSet countOfIndexesInRange:]`. - * @details Returns the number of indexes in the index set that are members of a given range. - Parameter range: Index range being inquired about. - Returns: Number of indexes in the index set that are members of 'indexRange'. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t count_of_indexes_in_range(const Range& range) const; /** * @brief Calls `-[NSIndexSet enumerateIndexesInRange:options:usingBlock:]`. - * @details Executes a given block using the indexes in the specified range, using the specified enumeration options. This method executes synchronously. - Parameters: - range: The range to enumerate. - opts: A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). - block: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). * @param range Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. @@ -81,20 +75,17 @@ namespace cocoon void enumerate_indexes_in_range(const Range& range, EnumerationOptions opts, std::function block) const; /** * @brief Calls `-[NSIndexSet enumerateIndexesUsingBlock:]`. - * @details Executes a given block using each object in the index set. This method executes synchronously. - Parameter block: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). * @param block Argument converted to the Objective-C parameter of the same role. */ void enumerate_indexes_using_block(std::function block) const; /** * @brief Calls `-[NSIndexSet enumerateIndexesWithOptions:usingBlock:]`. - * @details Executes a given block over the index set's indexes, using the specified enumeration options. This method executes synchronously. - Parameters: - opts: A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). - block: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). * @param opts Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. */ void enumerate_indexes_with_options(EnumerationOptions opts, std::function block) const; /** * @brief Calls `-[NSIndexSet enumerateRangesInRange:options:usingBlock:]`. - * @details Enumerates over the ranges in the range of objects using the block. By default, the enumeration starts with the first object and continues serially through the indexed set range to the last object in the range. You can specify 'NSEnumerationConcurrent' and/or 'NSEnumerationReverse' as enumeration options to modify this behavior. If the block parameter is 'nil' this method will raise an exception. This method executes synchronously. - Parameters: - range: The range of items to enumerate. If the range intersects a range of the receiver's indexes, then that intersection will be passed to the block. - opts: A bitmask that specifies the 'NSEnumerationOptions' for the enumeration. - block: The block to apply to elements in the index set. The block takes two arguments: 'range' (the range of elements) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). * @param range Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. @@ -102,20 +93,19 @@ namespace cocoon void enumerate_ranges_in_range(const Range& range, EnumerationOptions opts, std::function block) const; /** * @brief Calls `-[NSIndexSet enumerateRangesUsingBlock:]`. - * @details Executes a given block using each object in the index set, in the specified ranges. If the block parameter is 'nil' this method will raise an exception. This method executes synchronously. - Parameter block: The block to apply to elements in the index set. The block takes two arguments: 'range' (the range of elements) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). + * @details The following three convenience methods allow you to enumerate the indexes in the receiver by ranges of contiguous indexes. The performance of these methods is not guaranteed to be any better than if they were implemented with enumerateIndexesInRange:options:usingBlock:. However, depending on the receiver's implementation, they may perform better than that. If the specified range for enumeration intersects a range of contiguous indexes in the receiver, then the block will be invoked with the intersection of those two ranges. * @param block Argument converted to the Objective-C parameter of the same role. */ void enumerate_ranges_using_block(std::function block) const; /** * @brief Calls `-[NSIndexSet enumerateRangesWithOptions:usingBlock:]`. - * @details Executes a given block using each object in the index set, in the specified ranges. By default, the enumeration starts with the first object and continues serially through the indexed set range to the last object in the range. You can specify 'NSEnumerationConcurrent' and/or 'NSEnumerationReverse' as enumeration options to modify this behavior. If the block parameter is 'nil' this method will raise an exception. This method executes synchronously. - Parameters: - opts: A bitmask that specifies the 'NSEnumerationOptions' for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). - block: The block to apply to elements in the index set. The block takes two arguments: 'range' (the range of elements) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). * @param opts Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. */ void enumerate_ranges_with_options(EnumerationOptions opts, std::function block) const; /** * @brief Calls `-[NSIndexSet getIndexes:maxCount:inIndexRange:]`. - * @details The index set fills an index buffer with the indexes contained both in the index set and in an index range, returning the number of indexes copied. You are responsible for allocating the memory required for 'indexBuffer' and for releasing it later. Suppose you have an index set with contiguous indexes from 1 to 100. If you use this method to request a range of '(1, 100)' and specify a buffer size of '20', this method returns 20 indexes (1 through 20) in 'indexBuffer' and sets 'indexRange' to '(21, 80)'. Use this method to retrieve entries quickly and efficiently from an index set. You can call this method repeatedly to retrieve blocks of index values and then process them. When doing so, use the return value and 'indexRange' to determine when you have finished processing the desired indexes. When the return value is less than 'bufferSize', you have reached the end of the range. - Parameters: - indexBuffer: Index buffer to fill. - bufferSize: Maximum size of 'indexBuffer'. - range: Index range to compare with indexes in the index set; 'nil' represents all the indexes in the index set. On output, the range of indexes not copied to 'indexBuffer'. - Returns: Number of indexes placed in 'indexBuffer'. + * @details Fills up to bufferSize indexes in the specified range into the buffer and returns the number of indexes actually placed in the buffer; also modifies the optional range passed in by pointer to be "positioned" after the last index filled into the buffer.Example: if the index set contains the indexes 0, 2, 4, ..., 98, 100, for a buffer of size 10 and the range (20, 80) the buffer would contain 20, 22, ..., 38 and the range would be modified to (40, 60). * @param index_buffer Argument converted to the Objective-C parameter of the same role. * @param buffer_size Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -124,21 +114,18 @@ namespace cocoon std::uint64_t get_indexes(std::uint64_t* index_buffer, std::uint64_t buffer_size, Range* range) const; /** * @brief Calls `-[NSIndexSet indexGreaterThanIndex:]`. - * @details Returns either the closest index in the index set that is greater than a specific index or the not-found indicator. - Parameter value: Index being inquired about. - Returns: Closest index in the index set greater than 'index'; 'NSNotFound' when the index set contains no qualifying index. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t index_greater_than_index(std::uint64_t value) const; /** * @brief Calls `-[NSIndexSet indexGreaterThanOrEqualToIndex:]`. - * @details Returns either the closest index in the index set that is greater than or equal to a specific index or the not-found indicator. - Parameter value: Index being inquired about. - Returns: Closest index in the index set greater than or equal to 'index'; 'NSNotFound' when the index set contains no qualifying index. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t index_greater_than_or_equal_to_index(std::uint64_t value) const; /** * @brief Calls `-[NSIndexSet indexInRange:options:passingTest:]`. - * @details Returns the index of the first object in the specified range that passes the predicate block test. - Parameters: - range: The range of indexes to test. - opts: A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). - predicate: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). The block returns a Boolean value that indicates whether the index passed the test. - Returns: The index of the first object that passes the predicate test. * @param range Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. * @param predicate Argument converted to the Objective-C parameter of the same role. @@ -147,28 +134,24 @@ namespace cocoon std::uint64_t index_in_range(const Range& range, EnumerationOptions opts, std::function predicate) const; /** * @brief Calls `-[NSIndexSet indexLessThanIndex:]`. - * @details Returns either the closest index in the index set that is less than a specific index or the not-found indicator. - Parameter value: Index being inquired about. - Returns: Closest index in the index set less than 'index'; 'NSNotFound' when the index set contains no qualifying index. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t index_less_than_index(std::uint64_t value) const; /** * @brief Calls `-[NSIndexSet indexLessThanOrEqualToIndex:]`. - * @details Returns either the closest index in the index set that is less than or equal to a specific index or the not-found indicator. - Parameter value: Index being inquired about. - Returns: Closest index in the index set less than or equal to 'index'; 'NSNotFound' when the index set contains no qualifying index. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t index_less_than_or_equal_to_index(std::uint64_t value) const; /** * @brief Calls `-[NSIndexSet indexPassingTest:]`. - * @details Returns the index of the first object that passes the predicate block test. - Parameter predicate: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). The block returns a Boolean value that indicates whether the index passed the test. - Returns: The index of the first object that passes the predicate test. * @param predicate Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t index_passing_test(std::function predicate) const; /** * @brief Calls `-[NSIndexSet indexWithOptions:passingTest:]`. - * @details Returns the index of the first object that passes the predicate block test using the specified enumeration options. - Parameters: - opts: A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). - predicate: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). The block returns a Boolean value that indicates whether the index passed the test. - Returns: The index of the first object that passes the predicate test. * @param opts Argument converted to the Objective-C parameter of the same role. * @param predicate Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -176,7 +159,6 @@ namespace cocoon std::uint64_t index_with_options(EnumerationOptions opts, std::function predicate) const; /** * @brief Calls `-[NSIndexSet indexesInRange:options:passingTest:]`. - * @details Returns an 'NSIndexSet' containing the receiving index set's objects in the specified range that pass the block test. - Parameters: - range: The range of indexes to test. - opts: A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). - predicate: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). The block returns a Boolean value that indicates whether the index passed the test. - Returns: An 'NSIndexSet' containing the indexes of the receiving index set that passed the predicate block test. * @param range Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. * @param predicate Argument converted to the Objective-C parameter of the same role. @@ -185,14 +167,12 @@ namespace cocoon IndexSet indexes_in_range(const Range& range, EnumerationOptions opts, std::function predicate) const; /** * @brief Calls `-[NSIndexSet indexesPassingTest:]`. - * @details Returns an 'NSIndexSet' containing the receiving index set's objects that pass the block test. - Parameter predicate: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). The block returns a Boolean value that indicates whether the index passed the test. - Returns: An 'NSIndexSet' containing the indexes of the receiving index set that passed the predicate block test. * @param predicate Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ IndexSet indexes_passing_test(std::function predicate) const; /** * @brief Calls `-[NSIndexSet indexesWithOptions:passingTest:]`. - * @details Returns an 'NSIndexSet' containing the receiving index set's objects that pass the block test using the specified enumeration options. - Parameters: - opts: A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). - predicate: The block to apply to elements in the set. The block takes two arguments: 'idx' (the index of the object) and 'stop' (a reference to a Boolean value; set to 'YES' to stop further processing). The block returns a Boolean value that indicates whether the index passed the test. - Returns: An 'NSIndexSet' containing the indexes of the receiving index set that passed the predicate block test. * @param opts Argument converted to the Objective-C parameter of the same role. * @param predicate Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -200,33 +180,29 @@ namespace cocoon IndexSet indexes_with_options(EnumerationOptions opts, std::function predicate) const; /** * @brief Calls `-[NSIndexSet intersectsIndexesInRange:]`. - * @details Indicates whether the index set contains any of the indexes in a range. - Parameter range: Index range being inquired about. - Returns: 'YES' when the index set contains one or more of the indexes in 'indexRange', 'NO' otherwise. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool intersects_indexes_in_range(const Range& range) const; /** * @brief Calls `-[NSIndexSet isEqualToIndexSet:]`. - * @details Indicates whether the indexes in the receiving index set are the same indexes contained in another index set. - Parameter indexSet: Index set being inquired about. - Returns: 'YES' when the indexes in the receiving index set are the same indexes 'indexSet' contains, 'NO' otherwise. * @param index_set Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equal_to_index_set(const IndexSet& index_set) const; /** * @brief Returns the `count` property of `NSIndexSet`. - * @details The number of indexes in the index set. * @return The converted Objective-C result. */ std::uint64_t count() const; /** * @brief Returns the `firstIndex` property of `NSIndexSet`. - * @details The first index in the index set, or 'NSNotFound' when the index set is empty. + * @details The following six methods will return NSNotFound if there is no index in the set satisfying the query. * @return The converted Objective-C result. */ std::uint64_t first_index() const; /** * @brief Returns the `lastIndex` property of `NSIndexSet`. - * @details The last index in the index set, or 'NSNotFound' when the index set is empty. * @return The converted Objective-C result. */ std::uint64_t last_index() const; diff --git a/include/generated/index_specifier.h b/include/generated/index_specifier.h index 4406e899..0be73fad 100644 --- a/include/generated/index_specifier.h +++ b/include/generated/index_specifier.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSIndexSpecifier` (Foundation). - * @details A specifier representing an object in a collection (or container) with an index number. The script terms 'first' and 'front' specify the object with index '0', while 'last' specifies the object with index of 'count-1'. A negative index indicates a location by counting backward from the last object in the collection. You don't normally subclass 'NSIndexSpecifier'. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptObjectSpecifier. * @@ -47,13 +46,11 @@ namespace cocoon explicit IndexSpecifier(Adopt adopt); /** * @brief Returns the `index` property of `NSIndexSpecifier`. - * @details The index position of the object to be retrieved. * @return The converted Objective-C result. */ std::int64_t index() const; /** * @brief Sets the `index` property of `NSIndexSpecifier`. - * @details The index position of the object to be retrieved. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_index(std::int64_t value) const; diff --git a/include/generated/inflection_rule.h b/include/generated/inflection_rule.h index 5c8871ae..10791696 100644 --- a/include/generated/inflection_rule.h +++ b/include/generated/inflection_rule.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSInflectionRule` (Foundation). - * @details A rule that affects how an attributed string performs automatic grammatical agreement. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -31,20 +30,17 @@ namespace cocoon explicit InflectionRule(Adopt adopt); /** * @brief Calls `+[NSInflectionRule canInflectLanguage:]`. - * @details Returns a Boolean value that indicates whether inflection will work in the specified language code. * @param language Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool can_inflect_language(const std::string& language); /** * @brief Returns the `automaticRule` property of `NSInflectionRule`. - * @details Returns a rule that performs automatic grammar agreement based on the system's current locale and language settings. * @return The converted Objective-C result. */ static InflectionRule automatic_rule(); /** * @brief Returns the `canInflectPreferredLocalization` property of `NSInflectionRule`. - * @details A Boolean value that indicates whether inflection will work in the language of the main bundle's first preferred localization. * @return The converted Objective-C result. */ static bool can_inflect_preferred_localization(); diff --git a/include/generated/inflection_rule_explicit.h b/include/generated/inflection_rule_explicit.h index c39b271f..9d8b46b2 100644 --- a/include/generated/inflection_rule_explicit.h +++ b/include/generated/inflection_rule_explicit.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSInflectionRuleExplicit` (Foundation). - * @details An inflection rule that uses a morphology instance to determine how to inflect attributed strings. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref InflectionRule. * @@ -36,7 +35,6 @@ namespace cocoon explicit InflectionRuleExplicit(Adopt adopt); /** * @brief Returns the `morphology` property of `NSInflectionRuleExplicit`. - * @details The morphology used by the receiver. * @return The converted Objective-C result. */ Morphology morphology() const; diff --git a/include/generated/input_stream.h b/include/generated/input_stream.h index f057a49f..bff7ef5e 100644 --- a/include/generated/input_stream.h +++ b/include/generated/input_stream.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSInputStream` (Foundation). - * @details A stream that provides read-only stream functionality. ''InputStream'' is "toll-free bridged" with its Core Foundation counterpart, \. For more information on toll-free bridging, see [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2). \#\#\# Subclassing Notes 'NSInputStream' is an abstract superclass of a class cluster consisting of concrete subclasses of 'NSStream' that provide standard read-only access to stream data. Although 'NSInputStream' is probably sufficient for most situations requiring access to stream data, you can create a subclass of 'NSInputStream' if you want more specialized behavior (for example, you want to record statistics on the data in a stream). \#\#\#\# Methods to Override To create a subclass of 'NSInputStream' you may have to implement initializers for the type of stream data supported and suitably re-implement existing initializers. You must also provide complete implementations of the following methods: - ''read(:maxLength:)'' From the current read index, take up to the number of bytes specified in the second parameter from the stream and place them in the client-supplied buffer (first parameter). The buffer must be of the size specified by the second parameter. Return the actual number of bytes placed in the buffer; if there is nothing left in the stream, return '0'. Reset the index into the stream for the next read operation. - ''getBuffer(:length:)'' Return in 0(1) a pointer to the subclass-allocated buffer (first parameter). Return by reference in the second parameter the number of bytes actually put into the buffer. The buffer's contents are valid only until the next stream operation. Return \ if you cannot access data in the buffer; otherwise, return \. If this method is not appropriate for your type of stream, you may return \. - ''hasBytesAvailable'' Return \ if there is more data to read in the stream, \ if there is not. If you want to be semantically compatible with 'NSInputStream', return \ if a read must be attempted to determine if bytes are available. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Stream. * @@ -41,7 +40,6 @@ namespace cocoon explicit InputStream(Adopt adopt); /** * @brief Calls `-[NSInputStream getBuffer:length:]`. - * @details Returns by reference a pointer to a read buffer and, by reference, the number of bytes available, and returns a Boolean value that indicates whether the buffer is available. This buffer is only valid until the next stream operation. Subclassers may return 'NO' for this if it is not appropriate for the stream type. This may return 'NO' if the buffer is not available. - Parameters: - buffer: Upon return, contains a pointer to a read buffer. - len: Upon return, contains the number of bytes available. - Returns: 'YES' if the buffer is available, otherwise 'NO'. * @param buffer Argument converted to the Objective-C parameter of the same role. * @param len Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -49,7 +47,6 @@ namespace cocoon bool get_buffer(std::uint8_t** buffer, std::uint64_t* len) const; /** * @brief Calls `-[NSInputStream read:maxLength:]`. - * @details Reads up to a given number of bytes into a given buffer. - Parameters: - buffer: A data buffer. The buffer must be large enough to contain the number of bytes specified by 'len'. - len: The maximum number of bytes to read. - Returns: A positive number indicates the number of bytes read; '0' indicates that the end of the buffer was reached; '-1' means that the operation failed (more information about the error can be obtained with 'streamError'). * @param buffer Argument converted to the Objective-C parameter of the same role. * @param len Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -57,7 +54,6 @@ namespace cocoon std::int64_t read(std::uint8_t* buffer, std::uint64_t len) const; /** * @brief Returns the `hasBytesAvailable` property of `NSInputStream`. - * @details A Boolean value that indicates whether the receiver has bytes available to read. 'YES' if the stream has bytes available or if it is impossible to tell without actually doing the read. * @return The converted Objective-C result. */ bool has_bytes_available() const; diff --git a/include/generated/invocation.h b/include/generated/invocation.h index a85bb57f..88449820 100644 --- a/include/generated/invocation.h +++ b/include/generated/invocation.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSInvocation` (Foundation). - * @details An Objective-C message rendered as an object. ''NSInvocation'' objects are used to store and forward messages between objects and between applications, primarily by ''Timer'' objects and the distributed objects system. An ''NSInvocation'' object contains all the elements of an Objective-C message: a target, a selector, arguments, and the return value. Each of these elements can be set directly, and the return value is set automatically when the ''NSInvocation'' object is dispatched. An ''NSInvocation'' object can be repeatedly dispatched to different targets; its arguments can be modified between dispatch for varying results; even its selector can be changed to another with the same method signature (argument and return types). This flexibility makes ''NSInvocation'' useful for repeating messages with many arguments and variations; rather than retyping a slightly different expression for each message, you modify the ''NSInvocation'' object as needed each time before dispatching it to a new target. ''NSInvocation'' does not support invocations of methods with either variable numbers of arguments or 'union' arguments. You should use the ''invocationWithMethodSignature:'' class method to create ''NSInvocation'' objects; you should not create these objects using \ and \. This class does not retain the arguments for the contained invocation by default. If those objects might disappear between the time you create your instance of ''NSInvocation'' and the time you use it, you should explicitly retain the objects yourself or invoke the ''retainArguments'' method to have the invocation object retain them itself. > Note: > ''NSInvocation'' conforms to the ''NSCoding'' protocol, but only supports coding by an ''NSPortCoder''. ''NSInvocation'' does not support archiving. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,20 +46,17 @@ namespace cocoon explicit Invocation(Adopt adopt); /** * @brief Calls `-[NSInvocation getArgument:atIndex:]`. - * @details Returns by indirection the receiver's argument at a specified index. Indices 0 and 1 indicate the hidden arguments 'self' and 'cmd', respectively; these values can be retrieved directly with the 'target' and 'selector' properties. Use indices 2 and greater for the arguments normally passed in a message. - Parameter argumentLocation: An untyped buffer to hold the returned argument. - Parameter idx: An integer specifying the index of the argument to get. * @param argument_location Argument converted to the Objective-C parameter of the same role. * @param idx Argument converted to the Objective-C parameter of the same role. */ void get_argument(void* argument_location, std::int64_t idx) const; /** * @brief Calls `-[NSInvocation getReturnValue:]`. - * @details Gets the invocation's return value. - Parameter retLoc: An untyped buffer into which the invocation copies its return value. It should be large enough to accommodate the value. * @param ret_loc Argument converted to the Objective-C parameter of the same role. */ void get_return_value(void* ret_loc) const; /** * @brief Calls `-[NSInvocation invoke]`. - * @details Sends the receiver's message (with arguments) to its target and sets the return value. You must set the receiver's target, selector, and argument values before calling this method. */ void invoke() const; /** @@ -70,61 +66,51 @@ namespace cocoon void invoke_using_imp(void (*imp)()) const; /** * @brief Calls `-[NSInvocation invokeWithTarget:]`. - * @details Sets the receiver's target, sends the receiver's message (with arguments) to that target, and sets the return value. You must set the receiver's selector and argument values before calling this method. - Parameter target: The object to set as the receiver's target. * @param target Argument converted to the Objective-C parameter of the same role. */ void invoke_with_target(const Object& target) const; /** * @brief Calls `-[NSInvocation retainArguments]`. - * @details If the receiver hasn't already done so, retains the target and all object arguments of the receiver and copies all of its C-string arguments and blocks. For efficiency, newly created 'NSInvocation' objects don't retain or copy their arguments, nor do they retain their targets, copy C strings, or copy any associated blocks. You should instruct an 'NSInvocation' object to retain its arguments if you intend to cache it, because the arguments may otherwise be released before the invocation is invoked. */ void retain_arguments() const; /** * @brief Calls `-[NSInvocation setArgument:atIndex:]`. - * @details Sets an argument of the receiver. Indices 0 and 1 indicate the hidden arguments 'self' and 'cmd', respectively; you should set these values directly with the 'target' and 'selector' properties. Use indices 2 and greater for the arguments normally passed in a message. - Parameter argumentLocation: An untyped buffer containing an argument to be assigned to the receiver. - Parameter idx: An integer specifying the index of the argument. * @param argument_location Argument converted to the Objective-C parameter of the same role. * @param idx Argument converted to the Objective-C parameter of the same role. */ void set_argument(void* argument_location, std::int64_t idx) const; /** * @brief Calls `-[NSInvocation setReturnValue:]`. - * @details Sets the receiver's return value. This value is normally set when you send an 'invoke' or 'invokeWithTarget:' message. - Parameter retLoc: An untyped buffer whose contents are copied as the receiver's return value. * @param ret_loc Argument converted to the Objective-C parameter of the same role. */ void set_return_value(void* ret_loc) const; /** * @brief Returns the `argumentsRetained` property of `NSInvocation`. - * @details A Boolean value that indicates if the receiver has retained its arguments. * @return The converted Objective-C result. */ bool arguments_retained() const; /** * @brief Returns the `methodSignature` property of `NSInvocation`. - * @details The receiver's method signature. * @return The converted Objective-C result. */ MethodSignature method_signature() const; /** * @brief Returns the `selector` property of `NSInvocation`. - * @details The receiver's selector, or 0 if it hasn't been set. * @return The converted Objective-C result. */ std::string selector() const; /** * @brief Sets the `selector` property of `NSInvocation`. - * @details The receiver's selector, or 0 if it hasn't been set. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_selector(const std::string& value) const; /** * @brief Returns the `target` property of `NSInvocation`. - * @details The receiver's target, or 'nil' if the receiver has no target. The target is the receiver of the message sent by 'invoke'. * @return The converted Objective-C result. */ Object target() const; /** * @brief Sets the `target` property of `NSInvocation`. - * @details The receiver's target, or 'nil' if the receiver has no target. The target is the receiver of the message sent by 'invoke'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_target(const Object& value) const; diff --git a/include/generated/invocation_operation.h b/include/generated/invocation_operation.h index 52f1044b..dae44175 100644 --- a/include/generated/invocation_operation.h +++ b/include/generated/invocation_operation.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSInvocationOperation` (Foundation). - * @details An operation that manages the execution of a single encapsulated task specified as an invocation. The ''NSInvocationOperation'' class is a concrete subclass of ''Operation'' that you use to initiate an operation that consists of invoking a selector on a specified object. This class implements a non-concurrent operation. For more information on concurrent versus non-concurrent operations, see ''Operation''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Operation. * @@ -39,13 +38,11 @@ namespace cocoon explicit InvocationOperation(Adopt adopt); /** * @brief Returns the `invocation` property of `NSInvocationOperation`. - * @details The receiver's invocation object. The invocation object identifying the target object, selector, and parameters to use to execute the operation's task. * @return The converted Objective-C result. */ Invocation invocation() const; /** * @brief Returns the `result` property of `NSInvocationOperation`. - * @details The result of the invocation or method. The object returned by the method or an 'NSValue' object containing the return value if it is not an object. 'nil' if the method or invocation is not finished executing. * @return The converted Objective-C result. */ Object result() const; diff --git a/include/generated/iso8601_date_formatter.h b/include/generated/iso8601_date_formatter.h index b570633d..1756e29b 100644 --- a/include/generated/iso8601_date_formatter.h +++ b/include/generated/iso8601_date_formatter.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSISO8601DateFormatter` (Foundation). - * @details A formatter that converts between dates and their ISO 8601 string representations. The ''ISO8601DateFormatter'' class generates and parses string representations of dates following the [ISO 8601](http://www.iso.org/iso/home/standards/iso8601) standard. Use this class to create ISO 8601 representations of dates and create dates from text strings in ISO 8601 format. > Tip: > In Swift, you can use ''Date/ISO8601FormatStyle'' rather than ''ISO8601DateFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -49,21 +48,18 @@ namespace cocoon explicit ISO8601DateFormatter(Adopt adopt); /** * @brief Calls `-[NSISO8601DateFormatter dateFromString:]`. - * @details Creates and returns a date object from the specified ISO 8601 formatted string representation. - Parameter string: The ISO 8601 formatted string representation of a date. - Returns: A date object, or 'nil' if no valid date was found. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Date date_from_string(const std::string& string) const; /** * @brief Calls `-[NSISO8601DateFormatter stringFromDate:]`. - * @details Creates and returns an ISO 8601 formatted string representation of the specified date. - Parameter date: The date to be represented. - Returns: A user-readable string representing the date. * @param date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_date(const Date& date) const; /** * @brief Calls `+[NSISO8601DateFormatter stringFromDate:timeZone:formatOptions:]`. - * @details Creates a representation of the specified date with a given time zone and format options. - Parameters: - date: The date to be represented. - timeZone: The time zone used. - formatOptions: The options used. For possible values, see 'NSISO8601DateFormatOptions'. - Returns: A user-readable string representing the date. * @param date Argument converted to the Objective-C parameter of the same role. * @param time_zone Argument converted to the Objective-C parameter of the same role. * @param format_options Argument converted to the Objective-C parameter of the same role. @@ -72,25 +68,23 @@ namespace cocoon static std::string string_from_date(const Date& date, const TimeZone& time_zone, ISO8601DateFormatOptions format_options); /** * @brief Returns the `formatOptions` property of `NSISO8601DateFormatter`. - * @details Options for generating and parsing ISO 8601 date representations. The ISO 8601 specification allows for dates to be expressed in a variety of ways. You can configure the format used to parse and generate representations by specifying various combinations of format options. > Important: Resetting this property can incur a significant performance cost, > as it may cause internal state to be regenerated. * @return The converted Objective-C result. */ ISO8601DateFormatOptions format_options() const; /** * @brief Sets the `formatOptions` property of `NSISO8601DateFormatter`. - * @details Options for generating and parsing ISO 8601 date representations. The ISO 8601 specification allows for dates to be expressed in a variety of ways. You can configure the format used to parse and generate representations by specifying various combinations of format options. > Important: Resetting this property can incur a significant performance cost, > as it may cause internal state to be regenerated. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_format_options(ISO8601DateFormatOptions value) const; /** * @brief Returns the `timeZone` property of `NSISO8601DateFormatter`. - * @details The time zone used to create and parse date representations. When unspecified, GMT is used. Resetting this property can incur a significant performance cost, as it may cause internal state to be regenerated. + * @details Please note that there can be a significant performance cost when resetting these properties. Resetting each property can result in regenerating the entire CFDateFormatterRef, which can be very expensive. * @return The converted Objective-C result. */ TimeZone time_zone() const; /** * @brief Sets the `timeZone` property of `NSISO8601DateFormatter`. - * @details The time zone used to create and parse date representations. When unspecified, GMT is used. Resetting this property can incur a significant performance cost, as it may cause internal state to be regenerated. + * @details Please note that there can be a significant performance cost when resetting these properties. Resetting each property can result in regenerating the entire CFDateFormatterRef, which can be very expensive. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_time_zone(const TimeZone& value) const; diff --git a/include/generated/item_provider.h b/include/generated/item_provider.h index 4d55564d..df73b7b6 100644 --- a/include/generated/item_provider.h +++ b/include/generated/item_provider.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSItemProvider` (Foundation). - * @details An item provider for conveying data or a file between processes during drag-and-drop or copy-and-paste activities, or from a host app to an app extension. Starting in iOS 11, item providers play a central role in drag and drop, and in copy and paste. They continue to play a role with app extensions. The system uses an internal queue when calling the completion blocks for the 'NSItemProvider' class. When using an item provider with drag and drop, ensure that UI updates take place on the main queue as follows: '''swift DispatchQueue.main.async { // Work that impacts the user interface. } ''' \#\#\# App extension support An app extension typically encounters item providers when examining the ''NSExtensionItem/attachments'' property of an ''NSExtensionItem'' object. During that examination, the extension can use the ''hasItemConformingToTypeIdentifier(:)'' method to look for data that it recognizes. Item providers use \ values to identify the data they contain. After finding a type of data that your extension can use, it calls the ''loadItem(forTypeIdentifier:options:completionHandler:)'' method to load the actual data, which is delivered to the provided completion handler. You can create item providers to vend data to another process. An extension that modifies an original data item can create a new 'NSItemProvider' object to send back to the host app. When creating data items, you specify your data object and the type of that object. You can optionally use the ''previewImageHandler'' property to generate a preview image for your data. A single item provider may use custom blocks to provide its data in many different formats. When configuring an item provider, use the ''registerItem(forTypeIdentifier:loadHandler:)'' method to register your blocks and the formats each one supports. When a client requests data in a particular format, the item provider executes the corresponding block, which is then responsible for coercing the data to the appropriate type and returning it to the client. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -53,21 +52,18 @@ namespace cocoon explicit ItemProvider(Adopt adopt); /** * @brief Calls `-[NSItemProvider canLoadObjectOfClass:]`. - * @details Returns a Boolean value indicating whether an item provider can load objects of a specified class. - Parameter aClass: The object class for comparison. - Returns: 'YES' if the item provider can load objects of the class. * @param a_class Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool can_load_object_of_class(const std::string& a_class) const; /** * @brief Calls `-[NSItemProvider hasItemConformingToTypeIdentifier:]`. - * @details Returns a Boolean value indicating whether an item provider contains a data representation conforming to a specified universal type identifier, with a file options value of zero. - Parameter typeIdentifier: A string that represents the desired UTI. - Returns: 'YES' if the item provider has at least one item that conforms to the supplied type identifier. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool has_item_conforming_to_type_identifier(const std::string& type_identifier) const; /** * @brief Calls `-[NSItemProvider hasRepresentationConformingToTypeIdentifier:fileOptions:]`. - * @details Returns a Boolean value indicating whether an item provider contains a data representation conforming to a specified universal type identifier and to specified open-in-place behavior. To check all registered UTIs for type conformance, pass the value '0' in the 'fileOptions' parameter. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @param file_options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -75,7 +71,6 @@ namespace cocoon bool has_representation_conforming_to_type_identifier(const std::string& type_identifier, ItemProviderFileOptions file_options) const; /** * @brief Calls `-[NSItemProvider loadDataRepresentationForTypeIdentifier:completionHandler:]`. - * @details Asynchronously copies the provided, typed data into an 'NSData' object, returning a progress object. If the source app provides a folder URL, the 'NSData' object contains a zip archive with the folder as its top-level entry. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -83,7 +78,6 @@ namespace cocoon Progress load_data_representation_for_type_identifier(const std::string& type_identifier, std::function, Error)> completion_handler) const; /** * @brief Calls `-[NSItemProvider loadFileRepresentationForTypeIdentifier:completionHandler:]`. - * @details Asynchronously writes a copy of the provided, typed data to a temporary file, returning a progress object. This method writes a copy of the file's data to a temporary file, which the system deletes when the completion handler returns. Your program should copy or move the file within the completion handler. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -91,7 +85,6 @@ namespace cocoon Progress load_file_representation_for_type_identifier(const std::string& type_identifier, std::function completion_handler) const; /** * @brief Calls `-[NSItemProvider loadInPlaceFileRepresentationForTypeIdentifier:completionHandler:]`. - * @details Asynchronously opens a file in place, if possible, returning a progress object. The system sets the 'isInPlace' parameter to 'YES' if the system successfully opened the file in place, or 'NO' if it made a local copy. In either case, you must access the returned URL using an 'NSFileCoordinator'. If the system created a local copy of a file, it will be automatically deleted after your file coordinator relinquishes its read access to the file. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -106,7 +99,6 @@ namespace cocoon void load_item_for_type_identifier(const std::string& type_identifier, const std::vector>& options, std::function completion_handler) const; /** * @brief Calls `-[NSItemProvider loadObjectOfClass:completionHandler:]`. - * @details Asynchronously loads an object of a specified class to an item provider, returning a progress object. * @param a_class Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -114,7 +106,6 @@ namespace cocoon Progress load_object_of_class(const std::string& a_class, std::function completion_handler) const; /** * @brief Calls `-[NSItemProvider loadPreviewImageWithOptions:completionHandler:]`. - * @details Loads the preview image for the item that the item provider represents. To handle image preview yourself, provide a completion handler block that returns an 'NSData' or 'NSURL' object, or an instance of a platform-specific image class ('UIImage' or 'NSImage'). This method supports implicit type coercion for the item parameter of the completion block. - Parameters: - options: A dictionary of keys and values that provide information about the item, such as the size of an image. - completionHandler: A completion handler block to execute with the results. * @param options Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ @@ -132,7 +123,6 @@ namespace cocoon void register_cloud_kit_share_with_preparation_handler(std::function)> preparation_handler) const; /** * @brief Calls `-[NSItemProvider registerDataRepresentationForTypeIdentifier:visibility:loadHandler:]`. - * @details Registers a data-backed representation for an item, specifying item visibility and a load handler. Register higher-fidelity types first, followed by progressively lower-fidelity ones. This ordering helps consumers get the best representation they can handle. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @param visibility Argument converted to the Objective-C parameter of the same role. * @param load_handler Argument converted to the Objective-C parameter of the same role. @@ -140,7 +130,6 @@ namespace cocoon void register_data_representation_for_type_identifier(const std::string& type_identifier, ItemProviderRepresentationVisibility visibility, std::function, Error)>)> load_handler) const; /** * @brief Calls `-[NSItemProvider registerFileRepresentationForTypeIdentifier:fileOptions:visibility:loadHandler:]`. - * @details Registers a file-backed representation for an item, specifying file options, item visibility, and a load handler. If a destination app must access the represented file using a file coordinator, set the 'coordinated' parameter in the load handler block to 'YES'. To offer a representation backed by a file provider, return an 'NSURL' object that points to your app's file provider's container. The file provider extension is then invoked to retrieve the file when requested. To offer a representation backed by a file to open in place, set the 'fileOptions' parameter to 'NSItemProviderFileOptionOpenInPlace'; in addition, return an 'NSURL' object that points to your app's file provider's container. Open-in-place support requires that the file provider is visible in the Files app. If 'NSItemProviderFileOptionOpenInPlace' is not provided, the file will be copied before the load handler returns. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @param file_options Argument converted to the Objective-C parameter of the same role. * @param visibility Argument converted to the Objective-C parameter of the same role. @@ -149,21 +138,18 @@ namespace cocoon void register_file_representation_for_type_identifier(const std::string& type_identifier, ItemProviderFileOptions file_options, ItemProviderRepresentationVisibility visibility, std::function)> load_handler) const; /** * @brief Calls `-[NSItemProvider registerItemForTypeIdentifier:loadHandler:]`. - * @details Lazily registers an item, according to the item provider type coercion policy. Use this method to register blocks that can take the item provider's file or data object and convert it to a specific data format. Your 'loadHandler' block is executed when a client passes the same 'typeIdentifier' string to the 'loadItemForTypeIdentifier:options:completionHandler:' method. \@deprecated Use 'registerObjectOfClass:visibility:loadHandler:' instead. - Parameters: - typeIdentifier: A string that represents the desired UTI. - loadHandler: A block capable of returning the data item as the specified type. * @param type_identifier Argument converted to the Objective-C parameter of the same role. * @param load_handler Argument converted to the Objective-C parameter of the same role. */ void register_item_for_type_identifier(const std::string& type_identifier, std::function, std::string, std::vector>)> load_handler) const; /** * @brief Calls `-[NSItemProvider registerObject:visibility:]`. - * @details Adds representations of a specified object to an item provider, based on the object's implementation of the 'NSItemProviderWriting' protocol, adhering to a visibility specification. If a representation for a given UTI is already registered, it is preserved (duplicate representations are ignored). * @param object Argument converted to the Objective-C parameter of the same role. * @param visibility Argument converted to the Objective-C parameter of the same role. */ void register_object(const Object& object, ItemProviderRepresentationVisibility visibility) const; /** * @brief Calls `-[NSItemProvider registerObjectOfClass:visibility:loadHandler:]`. - * @details Lazily adds representations of a specified object class to an item provider, based on the object's implementation of the 'NSItemProviderWriting' protocol, adhering to a visibility specification. * @param a_class Argument converted to the Objective-C parameter of the same role. * @param visibility Argument converted to the Objective-C parameter of the same role. * @param load_handler Argument converted to the Objective-C parameter of the same role. @@ -171,7 +157,6 @@ namespace cocoon void register_object_of_class(const std::string& a_class, ItemProviderRepresentationVisibility visibility, std::function)> load_handler) const; /** * @brief Calls `-[NSItemProvider registeredTypeIdentifiersWithFileOptions:]`. - * @details Returns an array with a subset of type identifiers for the item provider, according to the specified file options, in the same order they were registered. To access the array of all registered UTIs, pass the value '0' in the 'fileOptions' parameter. - Parameter fileOptions: The file options to filter by. - Returns: An array of type identifier strings. * @param file_options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -188,19 +173,16 @@ namespace cocoon Size preferred_presentation_size() const; /** * @brief Returns the `previewImageHandler` property of `NSItemProvider`. - * @details The custom preview image handler block for the item provider. In your image handler block, return an ''NSURL'' object that specifies a file, or return an ''NSData'' object. * @return The converted Objective-C result. */ std::function, std::string, std::vector>)> preview_image_handler() const; /** * @brief Sets the `previewImageHandler` property of `NSItemProvider`. - * @details The custom preview image handler block for the item provider. In your image handler block, return an ''NSURL'' object that specifies a file, or return an ''NSData'' object. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_preview_image_handler(std::function, std::string, std::vector>)> value) const; /** * @brief Returns the `registeredTypeIdentifiers` property of `NSItemProvider`. - * @details The array of type identifiers for the item provider, in the same order they were registered. * @return The converted Objective-C result. */ std::vector registered_type_identifiers() const; @@ -211,13 +193,11 @@ namespace cocoon Rect source_frame() const; /** * @brief Returns the `suggestedName` property of `NSItemProvider`. - * @details The suggested name for the item. * @return The converted Objective-C result. */ std::string suggested_name() const; /** * @brief Sets the `suggestedName` property of `NSItemProvider`. - * @details The suggested name for the item. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_suggested_name(const std::string& value) const; diff --git a/include/generated/json_serialization.h b/include/generated/json_serialization.h index 955ee9b6..096884d1 100644 --- a/include/generated/json_serialization.h +++ b/include/generated/json_serialization.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSJSONSerialization` (Foundation). - * @details An object that converts between JSON and the equivalent Foundation objects. You use the ''JSONSerialization'' class to convert JSON to Foundation objects and convert Foundation objects to JSON. To convert a Foundation object to JSON, the object must have the following properties: - The top level object is an ''NSArray'' or ''NSDictionary'', unless you set the ''WritingOptions/fragmentsAllowed'' option. - All objects are instances of ''NSString'', ''NSNumber'', ''NSArray'', ''NSDictionary'', or ''NSNull''. - All dictionary keys are instances of ''NSString''. - Numbers are neither 'NaN' nor infinity. Other rules may apply. Calling ''isValidJSONObject(:)'' or attempting a conversion are the definitive ways to tell if the ''JSONSerialization'' class can convert given object to JSON data. > Note: > On iOS 7 and later and macOS 10.9 and later, ''JSONSerialization'' is thread safe. + * @details A class for converting JSON to Foundation objects and converting Foundation objects to JSON. An object that may be converted to JSON must have the following properties: - Top level object is an NSArray or NSDictionary - All objects are NSString, NSNumber, NSArray, NSDictionary, or NSNull - All dictionary keys are NSStrings - NSNumbers are not NaN or infinity * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -35,7 +35,7 @@ namespace cocoon explicit JSONSerialization(Adopt adopt); /** * @brief Calls `+[NSJSONSerialization JSONObjectWithData:options:error:]`. - * @details Returns a Foundation object from JSON data. Set the 'NSJSONReadingFragmentsAllowed' option if the parser should allow top-level objects that are not an 'NSArray' or 'NSDictionary'. Setting the 'NSJSONReadingMutableContainers' option will make the parser generate mutable 'NSArrays' and 'NSDictionaries'. Setting the 'NSJSONReadingMutableLeaves' option will make the parser generate mutable 'NSString' objects. The data must be in one of the 5 supported encodings listed in the JSON specification: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. The most efficient encoding to use for parsing is UTF-8. + * @details Create a Foundation object from JSON data. Set the NSJSONReadingAllowFragments option if the parser should allow top-level objects that are not an NSArray or NSDictionary. Setting the NSJSONReadingMutableContainers option will make the parser generate mutable NSArrays and NSDictionaries. Setting the NSJSONReadingMutableLeaves option will make the parser generate mutable NSString objects. If an error occurs during the parse, then the error parameter will be set and the result will be nil. The data must be in one of the 5 supported encodings listed in the JSON specification: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. The data may or may not have a BOM. The most efficient encoding to use for parsing is UTF-8, so if you have a choice in encoding the data passed to this method, use UTF-8. * @param data Argument converted to the Objective-C parameter of the same role. * @param opt Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -43,7 +43,7 @@ namespace cocoon static Object json_object_with_data(const std::vector& data, JSONReadingOptions opt); /** * @brief Calls `+[NSJSONSerialization JSONObjectWithStream:options:error:]`. - * @details Returns a Foundation object from a JSON data stream. The stream should be opened and configured. All other behavior of this method is the same as the 'JSONObjectWithData:options:error:' method. + * @details Create a JSON object from JSON data stream. The stream should be opened and configured. All other behavior of this method is the same as the JSONObjectWithData:options:error: method. * @param stream Argument converted to the Objective-C parameter of the same role. * @param opt Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -51,7 +51,7 @@ namespace cocoon static Object json_object_with_stream(const InputStream& stream, JSONReadingOptions opt); /** * @brief Calls `+[NSJSONSerialization dataWithJSONObject:options:error:]`. - * @details Returns JSON data from a Foundation object. If the object will not produce valid JSON then an exception will be thrown. Setting the 'NSJSONWritingPrettyPrinted' option will generate JSON with whitespace designed to make the output more readable. If that option is not set, the most compact possible JSON will be generated. The resulting data is encoded in UTF-8. + * @details Generate JSON data from a Foundation object. If the object will not produce valid JSON then an exception will be thrown. Setting the NSJSONWritingPrettyPrinted option will generate JSON with whitespace designed to make the output more readable. If that option is not set, the most compact possible JSON will be generated. If an error occurs, the error parameter will be set and the return value will be nil. The resulting data is a encoded in UTF-8. * @param obj Argument converted to the Objective-C parameter of the same role. * @param opt Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -59,14 +59,14 @@ namespace cocoon static std::vector data_with_json_object(const Object& obj, JSONWritingOptions opt); /** * @brief Calls `+[NSJSONSerialization isValidJSONObject:]`. - * @details Returns a Boolean value that indicates whether a given object can be converted to JSON data. The object must have the following properties: the top level object is an 'NSArray' or 'NSDictionary'; all objects are 'NSString', 'NSNumber', 'NSArray', 'NSDictionary', or 'NSNull'; all dictionary keys are 'NSString' instances; and 'NSNumber' values are not NaN or infinity. + * @details Returns YES if the given object can be converted to JSON data, NO otherwise. The object must have the following properties: - Top level object is an NSArray or NSDictionary - All objects are NSString, NSNumber, NSArray, NSDictionary, or NSNull - All dictionary keys are NSStrings - NSNumbers are not NaN or infinity Other rules may apply. Calling this method or attempting a conversion are the definitive ways to tell if a given object can be converted to JSON data. * @param obj Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool is_valid_json_object(const Object& obj); /** * @brief Calls `+[NSJSONSerialization writeJSONObject:toStream:options:error:]`. - * @details Writes a Foundation object as JSON into an output stream. The stream should be opened and configured. The return value is the number of bytes written to the stream, or '0' on error. All other behavior of this method is the same as the 'dataWithJSONObject:options:error:' method. + * @details Write JSON data into a stream. The stream should be opened and configured. The return value is the number of bytes written to the stream, or 0 on error. All other behavior of this method is the same as the dataWithJSONObject:options:error: method. * @param obj Argument converted to the Objective-C parameter of the same role. * @param stream Argument converted to the Objective-C parameter of the same role. * @param opt Argument converted to the Objective-C parameter of the same role. diff --git a/include/generated/keyed_archiver.h b/include/generated/keyed_archiver.h index 99f74988..a0cbd715 100644 --- a/include/generated/keyed_archiver.h +++ b/include/generated/keyed_archiver.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSKeyedArchiver` (Foundation). - * @details An encoder that stores an object's data to an archive referenced by keys. ''NSKeyedArchiver'', a concrete subclass of ''NSCoder'', provides a way to encode objects (and scalar values) into an architecture-independent format suitable for storage in a file. When you archive a set of objects, the archiver writes the class information and instance variables for each object to the archive. The companion class ''NSKeyedUnarchiver'' decodes the data in an archive and creates a set of objects equivalent to the original set. A keyed archive differs from a non-keyed archive in that all the objects and values encoded into the archive have names, or keys. When decoding a non-keyed archive, the decoder must decode values in the same order the original encoder used. When decoding a keyed archive, the decoder requests values by name, meaning it can decode values out of sequence or not at all. Keyed archives, therefore, provide better support for forward and backward compatibility. The keys given to encoded values must be unique only within the scope of the currently-encoding object. A keyed archive is hierarchical, so the keys used by object A to encode its instance variables don't conflict with the keys used by object B. This is true even if A and B are instances of the same class. Within a single object, however, the keys used by a subclass can conflict with keys used in its superclasses. An ''NSArchiver'' object can write the archive data to a file or to a mutable-data object (an instance of ''NSMutableData'') that you provide. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Coder. * @@ -71,21 +70,18 @@ namespace cocoon static std::vector archived_data_with_root_object(const Object& object, bool requires_secure_coding); /** * @brief Calls `-[NSKeyedArchiver classNameForClass:]`. - * @details Returns the class name with which this archiver encodes instances of a given class. Returns 'nil' if the receiver does not have a translation mapping for 'cls'. The class's separate translation map is not searched. * @param cls Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string class_name_for_class(const std::string& cls) const; /** * @brief Calls `-[NSKeyedArchiver encodeBool:forKey:]`. - * @details Encodes a given Boolean value and associates it with a key. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_bool(bool value, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeBytes:length:forKey:]`. - * @details Encodes a given number of bytes from a given C array of bytes and associates them with a key. * @param bytes Argument converted to the Objective-C parameter of the same role. * @param length Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. @@ -93,61 +89,52 @@ namespace cocoon void encode_bytes(const std::uint8_t* bytes, std::uint64_t length, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeConditionalObject:forKey:]`. - * @details Encodes a reference to a given object and associates it with a key only if it has been unconditionally encoded elsewhere in the archive. * @param object Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_conditional_object(const Object& object, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeDouble:forKey:]`. - * @details Encodes a given 'double' value and associates it with a key. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_double(double value, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeFloat:forKey:]`. - * @details Encodes a given 'float' value and associates it with a key. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_float(float value, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeInt32:forKey:]`. - * @details Encodes a given 32-bit integer value and associates it with a key. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_int32(int value, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeInt64:forKey:]`. - * @details Encodes a given 64-bit integer value and associates it with a key. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_int64(std::int64_t value, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeInt:forKey:]`. - * @details Encodes a given 'int' value and associates it with a key. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_int(int value, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver encodeObject:forKey:]`. - * @details Encodes a given object and associates it with a given key. * @param object Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_object(const Object& object, const std::string& key) const; /** * @brief Calls `-[NSKeyedArchiver finishEncoding]`. - * @details Instructs the receiver to construct the final data stream. No more values can be encoded after this method is called. You must call this method when finished. */ void finish_encoding() const; /** * @brief Calls `-[NSKeyedArchiver setClassName:forClass:]`. - * @details Sets a mapping for this archiver to encode instances of a given class with the provided name, rather than their real name. When encoding, the receiver's translation map overrides any translation that may also be present in the class's map. * @param coded_name Argument converted to the Objective-C parameter of the same role. * @param cls Argument converted to the Objective-C parameter of the same role. */ @@ -160,25 +147,21 @@ namespace cocoon std::vector encoded_data() const; /** * @brief Returns the `outputFormat` property of `NSKeyedArchiver`. - * @details The format in which the receiver encodes its data. The available formats are XML and binary. * @return The converted Objective-C result. */ PropertyListFormat output_format() const; /** * @brief Sets the `outputFormat` property of `NSKeyedArchiver`. - * @details The format in which the receiver encodes its data. The available formats are XML and binary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_output_format(PropertyListFormat value) const; /** * @brief Returns the `requiresSecureCoding` property of `NSKeyedArchiver`. - * @details Indicates whether the archiver requires all archived classes to resist object substitution attacks. If you set the archiver to require secure coding, it throws an exception if you attempt to archive a class which doesn't conform to 'NSSecureCoding'. Note that the getter is on the superclass, 'NSCoder'. See 'NSCoder' for more information about secure coding. Enabling secure coding doesn't change the output format of the archive. * @return The converted Objective-C result. */ bool requires_secure_coding() const; /** * @brief Sets the `requiresSecureCoding` property of `NSKeyedArchiver`. - * @details Indicates whether the archiver requires all archived classes to resist object substitution attacks. If you set the archiver to require secure coding, it throws an exception if you attempt to archive a class which doesn't conform to 'NSSecureCoding'. Note that the getter is on the superclass, 'NSCoder'. See 'NSCoder' for more information about secure coding. Enabling secure coding doesn't change the output format of the archive. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_requires_secure_coding(bool value) const; diff --git a/include/generated/keyed_unarchiver.h b/include/generated/keyed_unarchiver.h index 2fea5ef8..3de48023 100644 --- a/include/generated/keyed_unarchiver.h +++ b/include/generated/keyed_unarchiver.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSKeyedUnarchiver` (Foundation). - * @details A decoder that restores data from an archive referenced by keys. ''NSKeyedUnarchiver'' is a concrete subclass of ''NSCoder'' that defines methods for decoding a set of named objects (and scalar values) from a keyed archive. The ''NSKeyedArchiver'' class produces archives that this class can decode. The archiver creates keyed archive as a hierarchy of objects. The archiver treats each object as a namespace into which it can encode other objects. This means that an unarchiver can only decode objects encoded within the immediate scope of their parent object. Objects encoded elsewhere in the hierarchy — whether higher than, lower than, or parallel to this particular object — aren't accessible. In this way, the keys used by a particular object to encode its instance variables need to be unique only within the scope of that object. If you invoke one of the 'decode'-prefixed methods of this class using a key that does not exist in the archive, the return value indicates failure. This value varies by decoded type. For example, if a key does not exist in an archive, ''decodeBool(forKey:)'' returns \, ''decodeIntForKey:'' returns '0', and ''decodeObject(forKey:)'' returns 'nil'. ''NSKeyedUnarchiver'' supports limited type coercion for numeric types. You can use any of the integer decode methods to decode a value encoded as any type of integer, whether a standard 'Int' or an explicit 32-bit or 64-bit integer. Likewise, you can use the 'Float'- or 'Double'-returning decode methods to handle value encoded as a 'Float' or 'Double'. If an encoded value is too large to fit within the coerced type, the decoding method throws a ''NSExceptionName/rangeException''. Further, when trying to coerce a value to an incompatible type — for example decoding an 'Int' as a 'Float' — the decoding method throws an ''NSExceptionName/invalidUnarchiveOperationException''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Coder. * @@ -64,28 +63,24 @@ namespace cocoon using Coder::requires_secure_coding; /** * @brief Calls `-[NSKeyedUnarchiver classForClassName:]`. - * @details Returns the class from which this unarchiver instantiates an encoded object with a given class name. Returns 'nil' if the receiver does not have a translation mapping for 'codedName'. The class's separate translation map is not searched. * @param coded_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string class_for_class_name(const std::string& coded_name) const; /** * @brief Calls `-[NSKeyedUnarchiver containsValueForKey:]`. - * @details Returns a Boolean value that indicates whether the archive contains a value for a given key within the current decoding scope. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool contains_value_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeBoolForKey:]`. - * @details Decodes and returns a boolean value that was previously encoded and associated with the string key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool decode_bool_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeBytesForKey:returnedLength:]`. - * @details Decodes a buffer of data that was previously encoded with 'encodeBytes:length:forKey:' and associated with the string key. The buffer's length is returned by reference in 'lengthp'. The returned bytes are immutable, and they go away with the unarchiver, not the containing autorelease pool. * @param key Argument converted to the Objective-C parameter of the same role. * @param lengthp Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -93,54 +88,46 @@ namespace cocoon const std::uint8_t* decode_bytes_for_key(const std::string& key, std::uint64_t* lengthp) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeDoubleForKey:]`. - * @details Decodes and returns a double value that was previously encoded and associated with the string key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double decode_double_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeFloatForKey:]`. - * @details Decodes and returns a float value that was previously encoded and associated with the string key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ float decode_float_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeInt32ForKey:]`. - * @details Decodes and returns a 32-bit integer value that was previously encoded and associated with the string key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ int decode_int32_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeInt64ForKey:]`. - * @details Decodes and returns a 64-bit integer value that was previously encoded and associated with the string key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::int64_t decode_int64_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeIntForKey:]`. - * @details Decodes and returns an int value that was previously encoded and associated with the string key. If the encoded integer does not fit into the default integer size, the method raises an 'NSRangeException'. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ int decode_int_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver decodeObjectForKey:]`. - * @details Decodes and returns a previously-encoded object that was associated with the string key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object decode_object_for_key(const std::string& key) const; /** * @brief Calls `-[NSKeyedUnarchiver finishDecoding]`. - * @details Tells the receiver that you are finished decoding objects. Invoking this method allows the receiver to notify its delegate and to perform any final operations on the archive. */ void finish_decoding() const; /** * @brief Calls `-[NSKeyedUnarchiver setClass:forClassName:]`. - * @details Sets a mapping for this unarchiver to decode objects encoded with a given class name as instances of a given class instead. When decoding, the receiver's translation map overrides any translation that may also be present in the class's map. * @param cls Argument converted to the Objective-C parameter of the same role. * @param coded_name Argument converted to the Objective-C parameter of the same role. */ @@ -181,7 +168,7 @@ namespace cocoon static std::vector> unarchived_dictionary_with_keys_of_classes(const std::vector& key_classes, const std::vector& value_classes, const std::vector& data); /** * @brief Calls `+[NSKeyedUnarchiver unarchivedObjectOfClass:fromData:error:]`. - * @details Decodes the root object of the given class from the given archive, previously encoded by \\c NSKeyedArchiver. Enables \\c requiresSecureCoding and sets the \\c decodingFailurePolicy to \\c NSDecodingFailurePolicySetErrorAndReturn. Returns \\c nil if the given data is not valid or cannot be decoded, and sets the \\c error out parameter. \@important Make sure you have adopted \\c NSSecureCoding in the types you decode. If any call to a \\c decode -prefixed method fails, the default \\c decodingFailurePolicy sets the error rather than throwing an exception. In this case, the current and all subsequent decode calls return \\c 0 or \\c nil. + * @details Decodes the root object of the given class from the given archive, previously encoded by \\c NSKeyedArchiver. Enables \\c requiresSecureCoding and sets the \\c decodingFailurePolicy to \\c NSDecodingFailurePolicySetErrorAndReturn. Returns \\c nil if the given data is not valid or cannot be decoded, and sets the \\c error out parameter. * @param cls Argument converted to the Objective-C parameter of the same role. * @param data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -189,7 +176,7 @@ namespace cocoon static Object unarchived_object_of_class(const std::string& cls, const std::vector& data); /** * @brief Calls `+[NSKeyedUnarchiver unarchivedObjectOfClasses:fromData:error:]`. - * @details Decodes the root object of one of the given classes from the given archive, previously encoded by \\c NSKeyedArchiver. Enables \\c requiresSecureCoding and sets the \\c decodingFailurePolicy to \\c NSDecodingFailurePolicySetErrorAndReturn. Returns \\c nil if the given data is not valid or cannot be decoded, and sets the \\c error out parameter. \@important Make sure you have adopted \\c NSSecureCoding in the types you decode. If any call to a \\c decode -prefixed method fails, the default \\c decodingFailurePolicy sets the error rather than throwing an exception. In this case, the current and all subsequent decode calls return \\c 0 or \\c nil. + * @details Decodes the root object of one of the given classes from the given archive, previously encoded by \\c NSKeyedArchiver. Enables \\c requiresSecureCoding and sets the \\c decodingFailurePolicy to \\c NSDecodingFailurePolicySetErrorAndReturn. Returns \\c nil if the given data is not valid or cannot be decoded, and sets the \\c error out parameter. * @param classes Argument converted to the Objective-C parameter of the same role. * @param data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -197,25 +184,21 @@ namespace cocoon static Object unarchived_object_of_classes(const std::vector& classes, const std::vector& data); /** * @brief Returns the `decodingFailurePolicy` property of `NSKeyedUnarchiver`. - * @details The action to take when the unarchiver encounters decode failures. * @return The converted Objective-C result. */ DecodingFailurePolicy decoding_failure_policy() const; /** * @brief Sets the `decodingFailurePolicy` property of `NSKeyedUnarchiver`. - * @details The action to take when the unarchiver encounters decode failures. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_decoding_failure_policy(DecodingFailurePolicy value) const; /** * @brief Returns the `requiresSecureCoding` property of `NSKeyedUnarchiver`. - * @details Indicates whether the unarchiver requires all unarchived classes to resist object substitution attacks. When enabled, unarchiving a disallowed class throws an exception. Once enabled, attempting to set 'requiresSecureCoding' to 'NO' will throw an exception. This is to prevent classes from selectively turning secure coding off. This is designed to be set once at the top level and remain on. Note that the getter is on the superclass, 'NSCoder'. See 'NSCoder' for more information about secure coding. * @return The converted Objective-C result. */ bool requires_secure_coding() const; /** * @brief Sets the `requiresSecureCoding` property of `NSKeyedUnarchiver`. - * @details Indicates whether the unarchiver requires all unarchived classes to resist object substitution attacks. When enabled, unarchiving a disallowed class throws an exception. Once enabled, attempting to set 'requiresSecureCoding' to 'NO' will throw an exception. This is to prevent classes from selectively turning secure coding off. This is designed to be set once at the top level and remain on. Note that the getter is on the superclass, 'NSCoder'. See 'NSCoder' for more information about secure coding. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_requires_secure_coding(bool value) const; diff --git a/include/generated/length_formatter.h b/include/generated/length_formatter.h index 4134fc84..94618866 100644 --- a/include/generated/length_formatter.h +++ b/include/generated/length_formatter.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSLengthFormatter` (Foundation). - * @details A formatter that provides localized descriptions of linear distances, such as length and height measurements. > Note: > As of iOS 10, macOS 10.12, tvOS 10, and watchOS 3, Foundation provides the ''MeasurementFormatter'' class, which can be used to represent quantities of ''UnitLength'' to provide equivalent functionality to ''LengthFormatter''. You are encouraged to transition to these new Foundation Units and Measurements APIs whenever possible. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -51,14 +50,12 @@ namespace cocoon explicit LengthFormatter(Adopt adopt); /** * @brief Calls `-[NSLengthFormatter stringFromMeters:]`. - * @details Returns a length string for the provided value in meters. Formats a number in meters to a localized string with the locale-appropriate unit and an appropriate scale (e.g. 4.3m = 14.1ft in the US locale). * @param number_in_meters Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_meters(double number_in_meters) const; /** * @brief Calls `-[NSLengthFormatter stringFromValue:unit:]`. - * @details Returns a length string for the provided value and unit. * @param value Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -66,7 +63,6 @@ namespace cocoon std::string string_from_value(double value, LengthFormatterUnit unit) const; /** * @brief Calls `-[NSLengthFormatter unitStringFromMeters:usedUnit:]`. - * @details Returns a unit string based on the provided value in meters. Returns the locale-appropriate unit, the same unit used by 'stringFromMeters:'. * @param number_in_meters Argument converted to the Objective-C parameter of the same role. * @param unitp Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -74,7 +70,6 @@ namespace cocoon std::string unit_string_from_meters(double number_in_meters, LengthFormatterUnit* unitp) const; /** * @brief Calls `-[NSLengthFormatter unitStringFromValue:unit:]`. - * @details Returns a unit string for the provided value and unit. Returns a localized string of the given unit, and if the unit is singular or plural is based on the given number. * @param value Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -82,37 +77,31 @@ namespace cocoon std::string unit_string_from_value(double value, LengthFormatterUnit unit) const; /** * @brief Returns the `forPersonHeightUse` property of `NSLengthFormatter`. - * @details A Boolean value that indicates whether the resulting string represents a person's height. The default value is 'NO'. If set to 'YES', the number argument for 'stringFromMeters:' and 'unitStringFromMeters:usedUnit:' is considered as a person's height. * @return The converted Objective-C result. */ bool is_for_person_height_use() const; /** * @brief Sets the `forPersonHeightUse` property of `NSLengthFormatter`. - * @details A Boolean value that indicates whether the resulting string represents a person's height. The default value is 'NO'. If set to 'YES', the number argument for 'stringFromMeters:' and 'unitStringFromMeters:usedUnit:' is considered as a person's height. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_for_person_height_use(bool value) const; /** * @brief Returns the `numberFormatter` property of `NSLengthFormatter`. - * @details The number formatter used to format the numbers in a length string. The default value is an 'NSNumberFormatter' with 'NSNumberFormatterDecimalStyle'. * @return The converted Objective-C result. */ NumberFormatter number_formatter() const; /** * @brief Sets the `numberFormatter` property of `NSLengthFormatter`. - * @details The number formatter used to format the numbers in a length string. The default value is an 'NSNumberFormatter' with 'NSNumberFormatterDecimalStyle'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_number_formatter(const NumberFormatter& value) const; /** * @brief Returns the `unitStyle` property of `NSLengthFormatter`. - * @details The unit style used when creating string representations of length values. The default value is 'NSFormattingUnitStyleMedium'. * @return The converted Objective-C result. */ FormattingUnitStyle unit_style() const; /** * @brief Sets the `unitStyle` property of `NSLengthFormatter`. - * @details The unit style used when creating string representations of length values. The default value is 'NSFormattingUnitStyleMedium'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_unit_style(FormattingUnitStyle value) const; diff --git a/include/generated/linguistic_tagger.h b/include/generated/linguistic_tagger.h index c2dec574..a5270cb8 100644 --- a/include/generated/linguistic_tagger.h +++ b/include/generated/linguistic_tagger.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSLinguisticTagger` (Foundation). - * @details Analyze natural language text to tag part of speech and lexical class, identify names, perform lemmatization, and determine the language and script. \@DeprecationSummary { Use the \ framework instead. } ''NSLinguisticTagger'' provides a uniform interface to a variety of natural language processing functionality with support for many different languages and scripts. You can use this class to segment natural language text into paragraphs, sentences, or words, and tag information about those segments, such as part of speech, lexical class, lemma, script, and language. When you create a linguistic tagger, you specify what kind of information you're interested in by passing one or more ''NSLinguisticTagScheme'' values. Set the ''string'' property to the natural language text you want to analyze, and the linguistic tagger processes it according to the specified tag schemes. You can then enumerate over the tags in a specified range, using the methods described in Enumerating Linguistic Tags, to get the information requested for a given scheme and unit. \#\#\# Thread Safety A single instance of ''NSLinguisticTagger'' should not be used simultaneously from multiple threads. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,14 +46,14 @@ namespace cocoon explicit LinguisticTagger(Adopt adopt); /** * @brief Calls `+[NSLinguisticTagger availableTagSchemesForLanguage:]`. - * @details Returns the tag schemes available for a particular language on the current device. - Parameters: - language: A BCP-47 tag identifying the language. For example, "en" for English or "zh-Hans" for Chinese written using the Simplified Chinese script. - Returns: The available tag schemes. For possible values, see 'NSLinguisticTagScheme'. This is a convenience method for calling 'availableTagSchemesForUnit:language:', passing 'NSLinguisticTaggerUnitWord' as the linguistic unit. + * @details Clients wishing to know the tag schemes supported in NSLinguisticTagger for a particular language at the word level may query them with this method. The language should be specified using a standard abbreviation as with NSOrthography. * @param language Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector available_tag_schemes_for_language(const std::string& language); /** * @brief Calls `+[NSLinguisticTagger availableTagSchemesForUnit:language:]`. - * @details Returns the tag schemes available for a particular unit and language on the current device. - Parameters: - unit: The linguistic unit. For possible values, see 'NSLinguisticTaggerUnit'. - language: A BCP-47 tag identifying the language. For example, "en" for English or "zh-Hans" for Chinese written using the Simplified Chinese script. - Returns: The supported tag schemes. For possible values, see 'NSLinguisticTagScheme'. + * @details Clients wishing to know the tag schemes supported in NSLinguisticTagger for a particular unit and language may query them with this method. The language should be specified using a standard BCP-47 language tag as with NSOrthography. * @param unit Argument converted to the Objective-C parameter of the same role. * @param language Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -62,14 +61,13 @@ namespace cocoon static std::vector available_tag_schemes_for_unit(LinguisticTaggerUnit unit, const std::string& language); /** * @brief Calls `+[NSLinguisticTagger dominantLanguageForString:]`. - * @details Returns the dominant language for the specified string. - Parameters: - string: The string for which the dominant language is determined. - Returns: The BCP-47 tag identifying the dominant language of the string, or the tag "und" if a specific language cannot be determined. This is a convenience method for creating a new linguistic tagger, setting the 'string' property, and getting the 'dominantLanguage' property. + * @details The following class methods are conveniences for clients who wish to perform a single analysis on a string without having to create an instance of NSLinguisticTagger. If more than one tagging operation is needed on a given string, it is more efficient to use an explicit NSLinguisticTagger instance. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string dominant_language_for_string(const std::string& string); /** * @brief Calls `+[NSLinguisticTagger enumerateTagsForString:range:unit:scheme:options:orthography:usingBlock:]`. - * @details Enumerates over a given string and calls the specified block for each tag. - Parameters: - string: The string to enumerate over. - range: The range to analyze. - unit: The linguistic unit. For possible values, see 'NSLinguisticTaggerUnit'. - scheme: The tag scheme. For possible values, see 'NSLinguisticTagScheme'. - options: The linguistic tagger options to use. - orthography: The orthography of the string. If unspecified, the orthography is automatically detected. - block: The block to apply to ranges of the string. The block takes a tag, a token range, and a stop pointer as arguments. This is a convenience method for initializing a linguistic tagger, setting the 'string' property, and calling 'enumerateTagsInRange:unit:scheme:options:usingBlock:'. If you analyze the same string more than once, you should create a linguistic tagger object instead of calling this method. * @param string Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. @@ -81,7 +79,7 @@ namespace cocoon static void enumerate_tags_for_string(const std::string& string, const Range& range, LinguisticTaggerUnit unit, const std::string& scheme, LinguisticTaggerOptions options, const Orthography& orthography, std::function block); /** * @brief Calls `-[NSLinguisticTagger enumerateTagsInRange:scheme:options:usingBlock:]`. - * @details Enumerates over a given range of the string and calls the specified block for each tag. - Parameters: - range: The range to analyze. - tagScheme: The tag scheme. For possible values, see 'NSLinguisticTagScheme'. - opts: The linguistic tagger options to use. - block: The block to apply to ranges of the string. The block takes a tag, a token range, a sentence range, and a stop pointer as arguments. This is a convenience method for calling 'enumerateTagsInRange:unit:scheme:options:usingBlock:', passing 'NSLinguisticTaggerUnitWord' as the linguistic unit. + * @details Methods that do not specify a unit act at the word level. * @param range Argument converted to the Objective-C parameter of the same role. * @param tag_scheme Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. @@ -90,7 +88,7 @@ namespace cocoon void enumerate_tags_in_range(const Range& range, const std::string& tag_scheme, LinguisticTaggerOptions opts, std::function block) const; /** * @brief Calls `-[NSLinguisticTagger enumerateTagsInRange:unit:scheme:options:usingBlock:]`. - * @details Enumerates over a given range of the string for a particular unit and calls the specified block for each tag. - Parameters: - range: The range to analyze. - unit: The linguistic unit. For possible values, see 'NSLinguisticTaggerUnit'. - scheme: The tag scheme. For possible values, see 'NSLinguisticTagScheme'. - options: The linguistic tagger options to use. - block: The block to apply to ranges of the string. The block takes a tag, a token range, and a stop pointer as arguments. This method's block is called for all tokens intersecting a given range, supplying tags and ranges. + * @details The tagger will segment the string as needed into tokens for the given unit, and return those ranges along with a tag for any scheme in its array of tag schemes. The fundamental tagging method on NSLinguisticTagger is a block iterator, that iterates over all tokens intersecting a given range, supplying tags and ranges. There are several additional convenience methods, for obtaining a sentence range, information about a single token, or for obtaining information about all tokens intersecting a given range at once, in arrays. In each case, the charIndex or range passed in must not extend beyond the end of the tagger's string, or the methods will raise an exception. Note that a given instance of NSLinguisticTagger should not be used from more than one thread simultaneously. * @param range Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @param scheme Argument converted to the Objective-C parameter of the same role. @@ -100,7 +98,6 @@ namespace cocoon void enumerate_tags_in_range(const Range& range, LinguisticTaggerUnit unit, const std::string& scheme, LinguisticTaggerOptions options, std::function block) const; /** * @brief Calls `-[NSLinguisticTagger orthographyAtIndex:effectiveRange:]`. - * @details Returns the orthography at the index and also returns the effective range. - Parameters: - charIndex: The character index to begin examination. - effectiveRange: An NSRangePointer that, upon completion, contains the range of the orthography containing 'charIndex'. - Returns: The orthography for the location. * @param char_index Argument converted to the Objective-C parameter of the same role. * @param effective_range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -108,7 +105,7 @@ namespace cocoon Orthography orthography_at_index(std::uint64_t char_index, Range* effective_range) const; /** * @brief Calls `-[NSLinguisticTagger possibleTagsAtIndex:scheme:tokenRange:sentenceRange:scores:]`. - * @details Returns an array of possible tags for the given scheme at the specified range, supplying matching scores. - Parameters: - charIndex: The position of the initial character. - tagScheme: The tag scheme. See 'NSLinguisticTagScheme' for possible values. - tokenRange: The token range. - sentenceRange: The range of the sentence. - scores: Returns by reference an array of numeric scores indicating the likelihood that the range matches the tag scheme. - Returns: Returns an array of possible tags for the tag scheme at the specified location, starting with the most likely tag scheme. Calling this method is not recommended; for most use cases, this information is not as useful as what is provided by the methods described in Enumerating Linguistic Tags and Getting Linguistic Tags. + * @details Deprecated method for obtaining a list of possible tags for the token at a given index. * @param char_index Argument converted to the Objective-C parameter of the same role. * @param tag_scheme Argument converted to the Objective-C parameter of the same role. * @param token_range Argument converted to the Objective-C parameter of the same role. @@ -119,28 +116,27 @@ namespace cocoon std::vector possible_tags_at_index(std::uint64_t char_index, const std::string& tag_scheme, Range* token_range, Range* sentence_range, std::vector& scores) const; /** * @brief Calls `-[NSLinguisticTagger sentenceRangeForRange:]`. - * @details Returns a range covering all sentences intersecting the given range. - Parameters: - range: The character range. - Returns: Returns the range of the sentence. This is a convenience method for calling 'tokenRangeAtIndex:unit:', passing 'NSLinguisticTaggerUnitSentence' as the unit and the first position of the provided range. + * @details Returns a range covering all sentences intersecting the given range. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Range sentence_range_for_range(const Range& range) const; /** * @brief Calls `-[NSLinguisticTagger setOrthography:range:]`. - * @details Sets the orthography for the specified range. - Parameters: - orthography: The orthography. - range: The range. If the orthography of the linguistic tagger is not set, it will determine it automatically from the contents of the text. You should call this method only if you know the orthography of the text by some other means. + * @details If clients know the orthography for a given portion of the string, they may supply it to the tagger. Otherwise, the tagger will infer the language from the contents of the text. In each case, the charIndex or range passed in must not extend beyond the end of the tagger's string, or the methods will raise an exception. * @param orthography Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. */ void set_orthography(const Orthography& orthography, const Range& range) const; /** * @brief Calls `-[NSLinguisticTagger stringEditedInRange:changeInLength:]`. - * @details Notifies the linguistic tagger that the string (if mutable) has changed as specified by the parameters. - Parameters: - newRange: The range in the final string that was edited. - delta: The change in length. + * @details If the string attached to the tagger is mutable, this method must be called to inform the tagger whenever the string changes. The newRange is the range in the final string which was explicitly edited, and delta is the change in length from the previous version to the current version of the string. Alternatively, the client may call setString: again to reset all information about the string, but this has the disadvantage of not preserving information about portions of the string that have not changed. * @param new_range Argument converted to the Objective-C parameter of the same role. * @param delta Argument converted to the Objective-C parameter of the same role. */ void string_edited_in_range(const Range& new_range, std::int64_t delta) const; /** * @brief Calls `-[NSLinguisticTagger tagAtIndex:scheme:tokenRange:sentenceRange:]`. - * @details Returns a tag for a single scheme at the specified character position. - Parameters: - charIndex: The position of the initial character. - scheme: The tag scheme. See 'NSLinguisticTagScheme' for the possible values. - tokenRange: A pointer to the token range. - sentenceRange: A pointer to the range of the sentence. - Returns: Returns the tag for the requested tag scheme, or 'nil'. If a tag is returned, this function returns by reference the range of the token to 'tokenRange', and the range of the enclosing sentence to 'sentenceRange', if applicable. This is a convenience method for calling 'tagAtIndex:unit:scheme:tokenRange:' and passing 'NSLinguisticTaggerUnitWord' as the linguistic unit. * @param char_index Argument converted to the Objective-C parameter of the same role. * @param scheme Argument converted to the Objective-C parameter of the same role. * @param token_range Argument converted to the Objective-C parameter of the same role. @@ -150,7 +146,6 @@ namespace cocoon std::string tag_at_index(std::uint64_t char_index, const std::string& scheme, Range* token_range, Range* sentence_range) const; /** * @brief Calls `-[NSLinguisticTagger tagAtIndex:unit:scheme:tokenRange:]`. - * @details Returns a tag for a single scheme, for a given linguistic unit, at the specified character position. - Parameters: - charIndex: The position of the initial character. - unit: The linguistic unit. See 'NSLinguisticTaggerUnit' for possible values. - scheme: The tag scheme. See 'NSLinguisticTagScheme' for possible values. - tokenRange: A pointer to the token range. - Returns: Returns the tag for the requested tag scheme and linguistic unit, or 'nil'. If a tag is returned, this function returns by reference the range of the token to 'tokenRange'. * @param char_index Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @param scheme Argument converted to the Objective-C parameter of the same role. @@ -160,7 +155,6 @@ namespace cocoon std::string tag_at_index(std::uint64_t char_index, LinguisticTaggerUnit unit, const std::string& scheme, Range* token_range) const; /** * @brief Calls `+[NSLinguisticTagger tagForString:atIndex:unit:scheme:orthography:tokenRange:]`. - * @details Returns a tag for a single scheme, for a given linguistic unit, at the specified character position in a string. - Parameters: - string: The string to analyze. - charIndex: The position of the initial character. - unit: The linguistic unit. See 'NSLinguisticTaggerUnit' for possible values. - scheme: The tag scheme. See 'NSLinguisticTagScheme' for possible values. - orthography: The orthography of the string. If unspecified, the orthography is automatically detected. - tokenRange: A pointer to the token range. - Returns: Returns the tag for the requested tag scheme and linguistic unit, or 'nil'. This is a convenience method for initializing a linguistic tagger, setting the 'string' property, and calling 'tagAtIndex:unit:scheme:tokenRange:'. If you analyze the same string more than once, you should create a linguistic tagger object instead of calling this method. * @param string Argument converted to the Objective-C parameter of the same role. * @param char_index Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. @@ -172,7 +166,6 @@ namespace cocoon static std::string tag_for_string(const std::string& string, std::uint64_t char_index, LinguisticTaggerUnit unit, const std::string& scheme, const Orthography& orthography, Range* token_range); /** * @brief Calls `+[NSLinguisticTagger tagsForString:range:unit:scheme:options:orthography:tokenRanges:]`. - * @details Returns an array of linguistic tags and token ranges for a given string and linguistic unit. - Parameters: - string: The string to analyze. - range: The range from which to return tags. - unit: The linguistic unit. See 'NSLinguisticTaggerUnit' for possible values. - scheme: The tag scheme. See 'NSLinguisticTagScheme' for possible values. - options: The linguistic tagger options to use. - orthography: The orthography of the string. If unspecified, the orthography is automatically detected. - tokenRanges: Returns by reference an array of token ranges. - Returns: An array of the tags in the requested range. This is a convenience method for initializing a linguistic tagger, setting the 'string' property, and calling 'tagsInRange:unit:scheme:options:tokenRanges:'. If you analyze the same string more than once, you should create a linguistic tagger object instead of calling this method. * @param string Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. @@ -185,7 +178,6 @@ namespace cocoon static std::vector tags_for_string(const std::string& string, const Range& range, LinguisticTaggerUnit unit, const std::string& scheme, LinguisticTaggerOptions options, const Orthography& orthography, std::vector& token_ranges); /** * @brief Calls `-[NSLinguisticTagger tagsInRange:scheme:options:tokenRanges:]`. - * @details Returns an array of linguistic tags and token ranges for a given string range. - Parameters: - range: The range from which to return tags. - tagScheme: The tag scheme. See 'NSLinguisticTagScheme' for possible values. - opts: The linguistic tagger options to use. - tokenRanges: Returns by reference an array of token ranges. - Returns: An array of the tags in the requested range. This is a convenience method for calling 'tagsInRange:unit:scheme:options:tokenRanges:' and passing 'NSLinguisticTaggerUnitWord' as the linguistic unit. * @param range Argument converted to the Objective-C parameter of the same role. * @param tag_scheme Argument converted to the Objective-C parameter of the same role. * @param opts Argument converted to the Objective-C parameter of the same role. @@ -195,7 +187,6 @@ namespace cocoon std::vector tags_in_range(const Range& range, const std::string& tag_scheme, LinguisticTaggerOptions opts, std::vector& token_ranges) const; /** * @brief Calls `-[NSLinguisticTagger tagsInRange:unit:scheme:options:tokenRanges:]`. - * @details Returns an array of linguistic tags and token ranges for a given string range and linguistic unit. - Parameters: - range: The range from which to return tags. - unit: The linguistic unit. See 'NSLinguisticTaggerUnit' for possible values. - scheme: The tag scheme. See 'NSLinguisticTagScheme' for possible values. - options: The linguistic tagger options to use. - tokenRanges: Returns by reference an array of token ranges. - Returns: An array of the tags in the requested range. * @param range Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @param scheme Argument converted to the Objective-C parameter of the same role. @@ -206,7 +197,7 @@ namespace cocoon std::vector tags_in_range(const Range& range, LinguisticTaggerUnit unit, const std::string& scheme, LinguisticTaggerOptions options, std::vector& token_ranges) const; /** * @brief Calls `-[NSLinguisticTagger tokenRangeAtIndex:unit:]`. - * @details Returns the range of the linguistic unit containing the specified character index. - Parameters: - charIndex: The character index to begin examination. - unit: The linguistic unit. For possible values, see 'NSLinguisticTaggerUnit'. - Returns: The range of the substring for the linguistic unit. + * @details Returns the range corresponding to the token for the given unit that contains the given character index. * @param char_index Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -214,25 +205,22 @@ namespace cocoon Range token_range_at_index(std::uint64_t char_index, LinguisticTaggerUnit unit) const; /** * @brief Returns the `dominantLanguage` property of `NSLinguisticTagger`. - * @details Returns the dominant language of the string set for the linguistic tagger. Returns the BCP-47 tag identifying the dominant language of the string, or the tag "und" if a specific language cannot be determined. + * @details Returns the top identified language (if any) for the entire string. Convenience for tagAtIndex: with NSLinguisticTagSchemeLanguage and NSLinguisticTaggerUnitDocument. * @return The converted Objective-C result. */ std::string dominant_language() const; /** * @brief Returns the `string` property of `NSLinguisticTagger`. - * @details The string being analyzed by the linguistic tagger. * @return The converted Objective-C result. */ std::string string() const; /** * @brief Sets the `string` property of `NSLinguisticTagger`. - * @details The string being analyzed by the linguistic tagger. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_string(const std::string& value) const; /** * @brief Returns the `tagSchemes` property of `NSLinguisticTagger`. - * @details Returns the tag schemes configured for this linguistic tagger. * @return The converted Objective-C result. */ std::vector tag_schemes() const; diff --git a/include/generated/list_formatter.h b/include/generated/list_formatter.h index d20883b4..6a8c487c 100644 --- a/include/generated/list_formatter.h +++ b/include/generated/list_formatter.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSListFormatter` (Foundation). - * @details An object that provides locale-correct formatting of a list of items using the appropriate separator and conjunction. The list formatter isn't aware of the context where the formatted string will be used and doesn't provide capitalization customization of the list items. The formatted result may not be grammatically correct if placed in a sentence, and it should only be used in a standalone manner. + * @details NSListFormatter provides locale-correct formatting of a list of items using the appropriate separator and conjunction. Note that the list formatter is unaware of the context where the joined string will be used, e.g., in the beginning of the sentence or used as a standalone string in the UI, so it will not provide any sort of capitalization customization on the given items, but merely join them as-is. The string joined this way may not be grammatically correct when placed in a sentence, and it should only be used in a standalone manner. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -48,46 +48,46 @@ namespace cocoon using Formatter::string_for_object_value; /** * @brief Calls `+[NSListFormatter localizedStringByJoiningStrings:]`. - * @details Returns a string constructed from an array of strings using the list format specific to the current locale. It is recommended to join only disjointed strings that are ready to display in a bullet-point list. Sentences, phrases with punctuations, and appositions may not work well when joined together. + * @details Convenience method to return a string constructed from an array of strings using the list format specific to the current locale. It is recommended to join only disjointed strings that are ready to display in a bullet-point list. Sentences, phrases with punctuations, and appositions may not work well when joined together. * @param strings Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string localized_string_by_joining_strings(const std::vector& strings); /** * @brief Calls `-[NSListFormatter stringForObjectValue:]`. - * @details Creates a formatted string for an array of items. The list formatter uses 'itemFormatter' to format each item in the array. If 'itemFormatter' doesn't apply to a particular item, the list formatter falls back to the item's 'description(withLocale:)' or 'localizedDescription' if implemented. If those methods aren't implemented, the formatter uses 'description' instead. - Parameters: - obj: An array of objects to format as a list. - Returns: A formatted string representing the list of objects in an array. Returns 'nil' if the formatter can't generate a description for all objects in the array, or if 'obj' is 'nil'. + * @details Inherited from NSFormatter. 'obj' must be an instance of NSArray. Returns nil if 'obj' is nil, not an instance of NSArray, or if the list formatter cannot generate a string representation for all objects in the array. * @param obj Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_for_object_value(const Object& obj) const; /** * @brief Calls `-[NSListFormatter stringFromItems:]`. - * @details Returns a string constructed from an array using the locale-aware format. Each item is formatted using the 'itemFormatter'. If the 'itemFormatter' does not apply to a particular item, the method will fall back to the item's 'descriptionWithLocale:' or 'localizedDescription' if implemented, or 'description' if not. Returns 'nil' if 'items' is 'nil' or if the list formatter cannot generate a string representation for all items in the array. + * @details Convenience method for -stringForObjectValue:. Returns a string constructed from an array in the locale-aware format. Each item is formatted using the itemFormatter. If the itemFormatter does not apply to a particular item, the method will fall back to the item's -descriptionWithLocale: or -localizedDescription if implemented, or -description if not. Returns nil if 'items' is nil or if the list formatter cannot generate a string representation for all items in the array. * @param items Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_items(const std::vector& items) const; /** * @brief Returns the `itemFormatter` property of `NSListFormatter`. - * @details Specifies how each object should be formatted. If not set, the object is formatted using its instance method in the following order: 'descriptionWithLocale:', 'localizedDescription', and 'description'. + * @details Specifies how each object should be formatted. If not set, the object is formatted using its instance method in the following order: -descriptionWithLocale:, -localizedDescription, and -description. * @return The converted Objective-C result. */ Formatter item_formatter() const; /** * @brief Sets the `itemFormatter` property of `NSListFormatter`. - * @details Specifies how each object should be formatted. If not set, the object is formatted using its instance method in the following order: 'descriptionWithLocale:', 'localizedDescription', and 'description'. + * @details Specifies how each object should be formatted. If not set, the object is formatted using its instance method in the following order: -descriptionWithLocale:, -localizedDescription, and -description. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_item_formatter(const Formatter& value) const; /** * @brief Returns the `locale` property of `NSListFormatter`. - * @details Specifies the locale to format the items. Defaults to 'autoupdatingCurrentLocale'. Also resets to 'autoupdatingCurrentLocale' on assignment of 'nil'. + * @details Specifies the locale to format the items. Defaults to autoupdatingCurrentLocale. Also resets to autoupdatingCurrentLocale on assignment of nil. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSListFormatter`. - * @details Specifies the locale to format the items. Defaults to 'autoupdatingCurrentLocale'. Also resets to 'autoupdatingCurrentLocale' on assignment of 'nil'. + * @details Specifies the locale to format the items. Defaults to autoupdatingCurrentLocale. Also resets to autoupdatingCurrentLocale on assignment of nil. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; diff --git a/include/generated/locale.h b/include/generated/locale.h index 6c5514fc..6a747d83 100644 --- a/include/generated/locale.h +++ b/include/generated/locale.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSLocale` (Foundation). - * @details Information about linguistic, cultural, and technological conventions for use in formatting data for presentation. In Swift, this object bridges to ''Locale''; use ''NSLocale'' when you need reference semantics or other Foundation-specific behavior. You typically use a locale to format and interpret information about and according to the user's customs and preferences. You can initialize any number of locale instances with ''init(localeIdentifier:)'' using one of the locale identifiers found in the ''availableLocaleIdentifiers'' array. However, you usually use a locale configured to match the preferences of the current user. Use the ''current'' property to get the locale matching the current user's preferences. If you need to be alerted when the user does make changes to region settings, register for the ''currentLocaleDidChangeNotification'' notification. Alternatively, you can use the ''autoupdatingCurrent'' property to get a locale that automatically updates with the user's configuration settings: \@TabNavigator { \@Tab("Swift") { '''swift let locale = NSLocale.autoupdatingCurrent ''' } \@Tab("Objective-C") { '''objc NSLocale locale = [NSLocale autoupdatingCurrentLocale]; ''' } } You can inspect a locale by reading its properties, as listed in Getting Information About a Locale. For properties containing a code or identifier, you can then obtain a string suitable for presentation to the user with the methods listed in Getting Display Information About a Locale. For example, you can report the user's language as a string localized in that language using the autoupdating locale obtained in the previous example: \@TabNavigator { \@Tab("Swift") { '''swift let code = locale.languageCode! let language = locale.localizedString(forLanguageCode: code)! print("\\(language)") // Prints "English" for locale en_US, "français" for fr_FR ''' } \@Tab("Objective-C") { '''objc NSString code = locale.languageCode; NSString language = [locale localizedStringForLanguageCode:code]; NSLog(\@"\%\@",language); // Prints "English" for locale en_US, "français" for fr_FR ''' } } You frequently use a locale in conjunction with a formatter. For example, the ''DateFormatter'' class has a ''DateFormatter/locale'' property that ensures dates are converted to strings that match the user's expectations about date formatting. By default, this property indicates the user's current locale, which is usually the behavior you want, but you can instead set it to another locale instance to obtain a different output. See [Data Formatting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DataFormatting/DataFormatting.html\#//apple_ref/doc/uid/10000029i) for more information about working with formatters. ''NSLocale'' is toll-free bridged with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. > Important: > The Swift overlay to the Foundation framework provides the ''Locale'' structure, which bridges to the ''NSLocale'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,35 +43,30 @@ namespace cocoon explicit Locale(Adopt adopt); /** * @brief Calls `+[NSLocale canonicalLanguageIdentifierFromString:]`. - * @details Returns a canonical language identifier by mapping an arbitrary locale identification string to the canonical identifier. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string canonical_language_identifier_from_string(const std::string& string); /** * @brief Calls `+[NSLocale canonicalLocaleIdentifierFromString:]`. - * @details Returns the canonical identifier for a given locale identification string. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string canonical_locale_identifier_from_string(const std::string& string); /** * @brief Calls `+[NSLocale characterDirectionForLanguage:]`. - * @details Returns the direction of the sequence of characters in a line for the specified ISO language code. * @param iso_lang_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static LocaleLanguageDirection character_direction_for_language(const std::string& iso_lang_code); /** * @brief Calls `+[NSLocale componentsFromLocaleIdentifier:]`. - * @details Returns a dictionary that is the result of parsing a locale ID. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::map components_from_locale_identifier(const std::string& string); /** * @brief Calls `-[NSLocale displayNameForKey:value:]`. - * @details Returns the display name for the given locale component value. * @param key Argument converted to the Objective-C parameter of the same role. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -80,213 +74,180 @@ namespace cocoon std::string display_name_for_key(const std::string& key, const Object& value) const; /** * @brief Calls `+[NSLocale lineDirectionForLanguage:]`. - * @details Returns the direction of the sequence of lines for the specified ISO language code. * @param iso_lang_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static LocaleLanguageDirection line_direction_for_language(const std::string& iso_lang_code); /** * @brief Calls `+[NSLocale localeIdentifierFromComponents:]`. - * @details Returns a locale identifier from the components specified in a given dictionary. * @param dict Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string locale_identifier_from_components(const std::map& dict); /** * @brief Calls `+[NSLocale localeIdentifierFromWindowsLocaleCode:]`. - * @details Returns a locale identifier from a Windows locale code. * @param lcid Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string locale_identifier_from_windows_locale_code(unsigned int lcid); /** * @brief Calls `-[NSLocale localizedStringForCalendarIdentifier:]`. - * @details Returns a localized string for the specified calendar identifier. * @param calendar_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_calendar_identifier(const std::string& calendar_identifier) const; /** * @brief Calls `-[NSLocale localizedStringForCollationIdentifier:]`. - * @details Returns a localized string for the specified collation identifier. * @param collation_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_collation_identifier(const std::string& collation_identifier) const; /** * @brief Calls `-[NSLocale localizedStringForCollatorIdentifier:]`. - * @details Returns a localized string for the specified collator identifier. * @param collator_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_collator_identifier(const std::string& collator_identifier) const; /** * @brief Calls `-[NSLocale localizedStringForCountryCode:]`. - * @details Returns a localized string for the specified country or region code. * @param country_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_country_code(const std::string& country_code) const; /** * @brief Calls `-[NSLocale localizedStringForCurrencyCode:]`. - * @details Returns a localized string for the specified currency code. * @param currency_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_currency_code(const std::string& currency_code) const; /** * @brief Calls `-[NSLocale localizedStringForLanguageCode:]`. - * @details Returns a localized string for the specified language code. * @param language_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_language_code(const std::string& language_code) const; /** * @brief Calls `-[NSLocale localizedStringForLocaleIdentifier:]`. - * @details Returns a localized string for the specified locale identifier. * @param locale_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_locale_identifier(const std::string& locale_identifier) const; /** * @brief Calls `-[NSLocale localizedStringForScriptCode:]`. - * @details Returns a localized string for the specified script code. * @param script_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_script_code(const std::string& script_code) const; /** * @brief Calls `-[NSLocale localizedStringForVariantCode:]`. - * @details Returns a localized string for the specified variant code. * @param variant_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_for_variant_code(const std::string& variant_code) const; /** * @brief Calls `-[NSLocale objectForKey:]`. - * @details Returns the object corresponding to the specified key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object object_for_key(const std::string& key) const; /** * @brief Calls `+[NSLocale windowsLocaleCodeFromLocaleIdentifier:]`. - * @details Returns a Windows locale code from the locale identifier. * @param locale_identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static unsigned int windows_locale_code_from_locale_identifier(const std::string& locale_identifier); /** * @brief Returns the `ISOCountryCodes` property of `NSLocale`. - * @details An array of NSString objects that represents all known legal ISO country codes. * @return The converted Objective-C result. */ static std::vector iso_country_codes(); /** * @brief Returns the `ISOCurrencyCodes` property of `NSLocale`. - * @details An array of NSString objects that represents all known legal ISO currency codes. * @return The converted Objective-C result. */ static std::vector iso_currency_codes(); /** * @brief Returns the `ISOLanguageCodes` property of `NSLocale`. - * @details An array of NSString objects that represents all known legal ISO language codes. * @return The converted Objective-C result. */ static std::vector iso_language_codes(); /** * @brief Returns the `alternateQuotationBeginDelimiter` property of `NSLocale`. - * @details The begin quotation delimiter for the locale when using alternate quotation marks. * @return The converted Objective-C result. */ std::string alternate_quotation_begin_delimiter() const; /** * @brief Returns the `alternateQuotationEndDelimiter` property of `NSLocale`. - * @details The end quotation delimiter for the locale when using alternate quotation marks. * @return The converted Objective-C result. */ std::string alternate_quotation_end_delimiter() const; /** * @brief Returns the `autoupdatingCurrentLocale` property of `NSLocale`. - * @details A locale representing the user's region settings at the time the property is read. * @return The converted Objective-C result. */ static Locale autoupdating_current_locale(); /** * @brief Returns the `availableLocaleIdentifiers` property of `NSLocale`. - * @details An array of NSString objects, each of which identifies a locale available on the system. * @return The converted Objective-C result. */ static std::vector available_locale_identifiers(); /** * @brief Returns the `calendarIdentifier` property of `NSLocale`. - * @details The calendar identifier for the locale. * @return The converted Objective-C result. */ std::string calendar_identifier() const; /** * @brief Returns the `collationIdentifier` property of `NSLocale`. - * @details The collation identifier for the locale. * @return The converted Objective-C result. */ std::string collation_identifier() const; /** * @brief Returns the `collatorIdentifier` property of `NSLocale`. - * @details The collator identifier for the locale. * @return The converted Objective-C result. */ std::string collator_identifier() const; /** * @brief Returns the `commonISOCurrencyCodes` property of `NSLocale`. - * @details An array of common ISO currency codes. * @return The converted Objective-C result. */ static std::vector common_iso_currency_codes(); /** * @brief Returns the `countryCode` property of `NSLocale`. - * @details The country or region code for the locale. * @return The converted Objective-C result. */ std::string country_code() const; /** * @brief Returns the `currencyCode` property of `NSLocale`. - * @details The currency code for the locale. * @return The converted Objective-C result. */ std::string currency_code() const; /** * @brief Returns the `currencySymbol` property of `NSLocale`. - * @details The currency symbol for the locale. * @return The converted Objective-C result. */ std::string currency_symbol() const; /** * @brief Returns the `currentLocale` property of `NSLocale`. - * @details An object representing the user's current locale. * @return The converted Objective-C result. */ static Locale current_locale(); /** * @brief Returns the `decimalSeparator` property of `NSLocale`. - * @details The decimal separator for the locale. * @return The converted Objective-C result. */ std::string decimal_separator() const; /** * @brief Returns the `exemplarCharacterSet` property of `NSLocale`. - * @details The exemplar character set for the locale. * @return The converted Objective-C result. */ CharacterSet exemplar_character_set() const; /** * @brief Returns the `groupingSeparator` property of `NSLocale`. - * @details The grouping separator for the locale. * @return The converted Objective-C result. */ std::string grouping_separator() const; /** * @brief Returns the `languageCode` property of `NSLocale`. - * @details The language code for the locale. * @return The converted Objective-C result. */ std::string language_code() const; @@ -298,25 +259,21 @@ namespace cocoon std::string language_identifier() const; /** * @brief Returns the `localeIdentifier` property of `NSLocale`. - * @details The identifier for the locale. * @return The converted Objective-C result. */ std::string locale_identifier() const; /** * @brief Returns the `preferredLanguages` property of `NSLocale`. - * @details An ordered list of the user's preferred languages. * @return The converted Objective-C result. */ static std::vector preferred_languages(); /** * @brief Returns the `quotationBeginDelimiter` property of `NSLocale`. - * @details The begin quotation delimiter for the locale. * @return The converted Objective-C result. */ std::string quotation_begin_delimiter() const; /** * @brief Returns the `quotationEndDelimiter` property of `NSLocale`. - * @details The end quotation delimiter for the locale. * @return The converted Objective-C result. */ std::string quotation_end_delimiter() const; @@ -328,25 +285,21 @@ namespace cocoon std::string region_code() const; /** * @brief Returns the `scriptCode` property of `NSLocale`. - * @details The script code for the locale. * @return The converted Objective-C result. */ std::string script_code() const; /** * @brief Returns the `systemLocale` property of `NSLocale`. - * @details The default generic root locale with little localization. * @return The converted Objective-C result. */ static Locale system_locale(); /** * @brief Returns the `usesMetricSystem` property of `NSLocale`. - * @details A Boolean value that indicates whether the locale uses the metric system. * @return The converted Objective-C result. */ bool uses_metric_system() const; /** * @brief Returns the `variantCode` property of `NSLocale`. - * @details The variant code for the locale. * @return The converted Objective-C result. */ std::string variant_code() const; diff --git a/include/generated/lock.h b/include/generated/lock.h index bae14bef..be1a71d6 100644 --- a/include/generated/lock.h +++ b/include/generated/lock.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSLock` (Foundation). - * @details An object that coordinates the operation of multiple threads of execution within the same application. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,26 +44,22 @@ namespace cocoon explicit Lock(Adopt adopt); /** * @brief Calls `-[NSLock lockBeforeDate:]`. - * @details Attempts to acquire a lock before a given date and returns a Boolean value indicating whether the attempt was successful. * @param limit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool lock_before_date(const Date& limit) const; /** * @brief Calls `-[NSLock tryLock]`. - * @details Attempts to acquire a lock and immediately returns a Boolean value that indicates whether the attempt was successful. * @return The converted Objective-C result. */ bool try_lock() const; /** * @brief Returns the `name` property of `NSLock`. - * @details The name associated with the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSLock`. - * @details The name associated with the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; diff --git a/include/generated/logical_test.h b/include/generated/logical_test.h index 91c7444c..535ce227 100644 --- a/include/generated/logical_test.h +++ b/include/generated/logical_test.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSLogicalTest` (Foundation). - * @details A script whose test that combines other tests using logical AND, OR, or NOT operations. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptWhoseTest. * diff --git a/include/generated/mach_bootstrap_server.h b/include/generated/mach_bootstrap_server.h index e10a113a..6b5423e7 100644 --- a/include/generated/mach_bootstrap_server.h +++ b/include/generated/mach_bootstrap_server.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMachBootstrapServer` (Foundation). - * @details \@DeprecationSummary { Use ''NSXPCConnection'' instead. } A port name server that takes and returns Mach port objects. Port removal functionality is not supported in ''NSMachBootstrapServer''; if you want to cancel a service, you have to destroy the port (invalidate the ''NSMachPort'' given to ''registerPort:name:''). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref PortNameServer. * @@ -46,14 +45,12 @@ namespace cocoon using PortNameServer::register_port; /** * @brief Calls `-[NSMachBootstrapServer portForName:]`. - * @details Looks up and returns the port registered under the specified name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Port port_for_name(const std::string& name) const; /** * @brief Calls `-[NSMachBootstrapServer portForName:host:]`. - * @details Looks up and returns the port registered under the specified name on a given host. The bootstrap server is a local-only server; the host parameter must be an empty string or 'nil'. * @param name Argument converted to the Objective-C parameter of the same role. * @param host Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -61,7 +58,6 @@ namespace cocoon Port port_for_name(const std::string& name, const std::string& host) const; /** * @brief Calls `-[NSMachBootstrapServer registerPort:name:]`. - * @details Registers a given port as a network service with the specified name. * @param port Argument converted to the Objective-C parameter of the same role. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -69,14 +65,12 @@ namespace cocoon bool register_port(const Port& port, const std::string& name) const; /** * @brief Calls `-[NSMachBootstrapServer servicePortWithName:]`. - * @details Returns the port for the specified service name, requesting the launch of the corresponding service if it is not already running. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Port service_port_with_name(const std::string& name) const; /** * @brief Calls `+[NSMachBootstrapServer sharedInstance]`. - * @details Returns the shared instance of the Mach bootstrap server. * @return The converted Objective-C result. */ static Object shared_instance(); diff --git a/include/generated/mach_port.h b/include/generated/mach_port.h index aff585b7..663efa32 100644 --- a/include/generated/mach_port.h +++ b/include/generated/mach_port.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMachPort` (Foundation). - * @details A port that can be used as an endpoint for distributed object connections (or raw messaging). ''NSMachPort'' is a subclass of ''NSPort'' that wraps a Mach port, the fundamental communication port in macOS. ''NSMachPort'' allows for local (on the same machine) communication only. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Port. * @@ -53,20 +52,17 @@ namespace cocoon using Port::set_delegate; /** * @brief Calls `-[NSMachPort delegate]`. - * @details Returns the receiver's delegate. * @return The converted Objective-C result. */ Object delegate() const; /** * @brief Calls `+[NSMachPort portWithMachPort:]`. - * @details Creates and returns a port object with a given Mach port. * @param mach_port Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Port port_with_mach_port(unsigned int mach_port); /** * @brief Calls `+[NSMachPort portWithMachPort:options:]`. - * @details Creates and returns a port object with a given Mach port and the specified options. * @param mach_port Argument converted to the Objective-C parameter of the same role. * @param f Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -74,27 +70,23 @@ namespace cocoon static Port port_with_mach_port(unsigned int mach_port, MachPortOptions f); /** * @brief Calls `-[NSMachPort removeFromRunLoop:forMode:]`. - * @details Removes the port from a given run loop. * @param run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void remove_from_run_loop(const RunLoop& run_loop, const std::string& mode) const; /** * @brief Calls `-[NSMachPort scheduleInRunLoop:forMode:]`. - * @details Schedules the port on a given run loop. * @param run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void schedule_in_run_loop(const RunLoop& run_loop, const std::string& mode) const; /** * @brief Calls `-[NSMachPort setDelegate:]`. - * @details Sets the receiver's delegate to a given object. * @param an_object Argument converted to the Objective-C parameter of the same role. */ void set_delegate(const Object& an_object) const; /** * @brief Returns the `machPort` property of `NSMachPort`. - * @details The Mach port used by the receiver. * @return The converted Objective-C result. */ unsigned int mach_port() const; diff --git a/include/generated/map_table_base.h b/include/generated/map_table_base.h index bb89aa8c..a40f8d91 100644 --- a/include/generated/map_table_base.h +++ b/include/generated/map_table_base.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMapTable` (Foundation). - * @details A collection similar to a dictionary, but with a broader range of available memory semantics. The map table is modeled after ''NSDictionary'' with the following differences: - Keys and/or values are optionally held "weakly" such that entries are removed when one of the objects is reclaimed. - Its keys or values may be copied on input or may use pointer identity for equality and hashing. - It can contain arbitrary pointers (its contents are not constrained to being objects). You can configure an ''NSMapTable'' instance to operate on arbitrary pointers and not just objects, although typically you are encouraged to use the C function API for void \\ pointers. The object-based API (such as ''setObject(:forKey:)'') will not work for non-object pointers without type-casting. When configuring map tables, note that only the options listed in ''NSMapTableOptions'' guarantee that the rest of the API will work correctly—including copying, archiving, and fast enumeration. While other ''NSPointerFunctions'' options are used for certain configurations, such as to hold arbitrary pointers, not all combinations of the options are valid. With some combinations the map table may not work correctly, or may not even be initialized correctly. \#\#\# Subclassing Notes 'NSMapTable' is not suitable for subclassing. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref MapTable to supply KeyType, ObjectType. * @@ -51,19 +50,16 @@ namespace cocoon explicit MapTableBase(Adopt adopt); /** * @brief Calls `-[NSMapTable dictionaryRepresentation]`. - * @details Returns a dictionary representation of the map table. - Returns: A dictionary representation of the map table. * @return The converted Objective-C result. */ std::vector> dictionary_representation() const; /** * @brief Calls `-[NSMapTable keyEnumerator]`. - * @details Returns an enumerator object that lets you access each key in the map table. It is more efficient to use the fast enumeration protocol (see 'NSFastEnumeration'). - Returns: An enumerator object that lets you access each key in the map table. * @return The converted Objective-C result. */ EnumeratorBase key_enumerator() const; /** * @brief Calls `+[NSMapTable mapTableWithKeyOptions:valueOptions:]`. - * @details Returns a new map table, initialized with the given options. - Parameter keyOptions: A bit field that specifies the options for the keys in the map table. - Parameter valueOptions: A bit field that specifies the options for the values in the map table. - Returns: A new map table, initialized with the given options. * @param key_options Argument converted to the Objective-C parameter of the same role. * @param value_options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -71,74 +67,63 @@ namespace cocoon static MapTableBase map_table_with_key_options(PointerFunctionsOptions key_options, PointerFunctionsOptions value_options); /** * @brief Calls `-[NSMapTable objectEnumerator]`. - * @details Returns an enumerator object that lets you access each value in the map table. It is more efficient to use the fast enumeration protocol (see 'NSFastEnumeration'). - Returns: An enumerator object that lets you access each value in the map table. * @return The converted Objective-C result. */ EnumeratorBase object_enumerator() const; /** * @brief Calls `-[NSMapTable objectForKey:]`. - * @details Returns the value associated with a given key. - Parameter aKey: The key for which to return the corresponding value. - Returns: The value associated with 'aKey', or 'nil' if no value is associated with 'aKey'. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object object_for_key(const Object& a_key) const; /** * @brief Calls `-[NSMapTable removeAllObjects]`. - * @details Empties the map table of its entries. */ void remove_all_objects() const; /** * @brief Calls `-[NSMapTable removeObjectForKey:]`. - * @details Removes a given key and its associated value from the map table. Does nothing if 'aKey' does not exist. - Parameter aKey: The key to remove. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void remove_object_for_key(const Object& a_key) const; /** * @brief Calls `-[NSMapTable setObject:forKey:]`. - * @details Adds a given key-value pair to the map table. - Parameter anObject: The value for 'aKey'. - Parameter aKey: The key for 'anObject'. * @param an_object Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_object(const Object& an_object, const Object& a_key) const; /** * @brief Calls `+[NSMapTable strongToStrongObjectsMapTable]`. - * @details Returns a new map table object which has strong references to the keys and values. * @return The converted Objective-C result. */ static MapTableBase strong_to_strong_objects_map_table(); /** * @brief Calls `+[NSMapTable strongToWeakObjectsMapTable]`. - * @details Returns a new map table object which has strong references to the keys and weak references to the values. * @return The converted Objective-C result. */ static MapTableBase strong_to_weak_objects_map_table(); /** * @brief Calls `+[NSMapTable weakToStrongObjectsMapTable]`. - * @details Returns a new map table object which has weak references to the keys and strong references to the values. Use of weak-to-strong map tables is not recommended. The strong values for weak keys which get zeroed out continue to be maintained until the map table resizes itself. * @return The converted Objective-C result. */ static MapTableBase weak_to_strong_objects_map_table(); /** * @brief Calls `+[NSMapTable weakToWeakObjectsMapTable]`. - * @details Returns a new map table object which has weak references to the keys and values. * @return The converted Objective-C result. */ static MapTableBase weak_to_weak_objects_map_table(); /** * @brief Returns the `count` property of `NSMapTable`. - * @details The number of key-value pairs in the map table. * @return The converted Objective-C result. */ std::uint64_t count() const; /** * @brief Returns the `keyPointerFunctions` property of `NSMapTable`. - * @details The pointer functions the map table uses to manage keys. + * @details return an NSPointerFunctions object reflecting the functions in use. This is a new autoreleased object that can be subsequently modified and/or used directly in the creation of other pointer "collections". * @return The converted Objective-C result. */ PointerFunctions key_pointer_functions() const; /** * @brief Returns the `valuePointerFunctions` property of `NSMapTable`. - * @details The pointer functions the map table uses to manage values. * @return The converted Objective-C result. */ PointerFunctions value_pointer_functions() const; diff --git a/include/generated/mass_formatter.h b/include/generated/mass_formatter.h index 0b4e7744..fd386da5 100644 --- a/include/generated/mass_formatter.h +++ b/include/generated/mass_formatter.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMassFormatter` (Foundation). - * @details A formatter that provides localized descriptions of mass and weight values. > Note: > As of iOS 10, macOS 10.12, tvOS 10, and watchOS 3, Foundation provides the ''MeasurementFormatter'' class, which can be used to represent quantities of ''UnitMass'' to provide equivalent functionality to ''MassFormatter''. You are encouraged to transition to these new Foundation Units and Measurements APIs whenever possible. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -51,14 +50,12 @@ namespace cocoon explicit MassFormatter(Adopt adopt); /** * @brief Calls `-[NSMassFormatter stringFromKilograms:]`. - * @details Returns a mass string for the provided value in kilograms. Formats a number in kilograms to a localized string with the locale-appropriate unit and an appropriate scale (e.g. 1.2kg = 2.64lb in the US locale). * @param number_in_kilograms Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_kilograms(double number_in_kilograms) const; /** * @brief Calls `-[NSMassFormatter stringFromValue:unit:]`. - * @details Returns a mass string for the provided value and unit. * @param value Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -66,7 +63,6 @@ namespace cocoon std::string string_from_value(double value, MassFormatterUnit unit) const; /** * @brief Calls `-[NSMassFormatter unitStringFromKilograms:usedUnit:]`. - * @details Returns a unit string based on the provided value in kilograms. Returns the locale-appropriate unit, the same unit used by 'stringFromKilograms:'. * @param number_in_kilograms Argument converted to the Objective-C parameter of the same role. * @param unitp Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -74,7 +70,6 @@ namespace cocoon std::string unit_string_from_kilograms(double number_in_kilograms, MassFormatterUnit* unitp) const; /** * @brief Calls `-[NSMassFormatter unitStringFromValue:unit:]`. - * @details Returns a unit string for the provided value and unit. Returns a localized string of the given unit, and if the unit is singular or plural is based on the given number. * @param value Argument converted to the Objective-C parameter of the same role. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -82,37 +77,31 @@ namespace cocoon std::string unit_string_from_value(double value, MassFormatterUnit unit) const; /** * @brief Returns the `forPersonMassUse` property of `NSMassFormatter`. - * @details A Boolean value that indicates whether the resulting string represents a person's mass. The default value is 'NO'. If set to 'YES', the number argument for 'stringFromKilograms:' and 'unitStringFromKilograms:usedUnit:' is considered as a person's mass. * @return The converted Objective-C result. */ bool is_for_person_mass_use() const; /** * @brief Sets the `forPersonMassUse` property of `NSMassFormatter`. - * @details A Boolean value that indicates whether the resulting string represents a person's mass. The default value is 'NO'. If set to 'YES', the number argument for 'stringFromKilograms:' and 'unitStringFromKilograms:usedUnit:' is considered as a person's mass. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_for_person_mass_use(bool value) const; /** * @brief Returns the `numberFormatter` property of `NSMassFormatter`. - * @details The number formatter used to format the numbers in a mass string. The default value is an 'NSNumberFormatter' with 'NSNumberFormatterDecimalStyle'. * @return The converted Objective-C result. */ NumberFormatter number_formatter() const; /** * @brief Sets the `numberFormatter` property of `NSMassFormatter`. - * @details The number formatter used to format the numbers in a mass string. The default value is an 'NSNumberFormatter' with 'NSNumberFormatterDecimalStyle'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_number_formatter(const NumberFormatter& value) const; /** * @brief Returns the `unitStyle` property of `NSMassFormatter`. - * @details The unit style used when creating string representations of mass values. The default value is 'NSFormattingUnitStyleMedium'. * @return The converted Objective-C result. */ FormattingUnitStyle unit_style() const; /** * @brief Sets the `unitStyle` property of `NSMassFormatter`. - * @details The unit style used when creating string representations of mass values. The default value is 'NSFormattingUnitStyleMedium'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_unit_style(FormattingUnitStyle value) const; diff --git a/include/generated/measurement_base.h b/include/generated/measurement_base.h index b73b8223..4a5bff64 100644 --- a/include/generated/measurement_base.h +++ b/include/generated/measurement_base.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMeasurement` (Foundation). - * @details A numeric quantity labeled with a unit of measure, with support for unit conversion and unit-aware calculations. An ''NSMeasurement'' object represents a quantity and unit of measure. The ''NSMeasurement'' class provides a programmatic interface to converting measurements into different units, as well as calculating the sum or difference between two measurements. ''NSMeasurement'' objects are initialized with an ''Unit'' object and 'double' value. ''NSMeasurement'' objects are immutable, and cannot be changed after being created. You can use the ''MeasurementFormatter'' class to create localized string representations of ''NSMeasurement'' objects. > Important: > The Swift overlay to the Foundation framework provides the ''Measurement'' structure, which bridges to the ''NSMeasurement'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref Measurement to supply UnitType. * @@ -44,41 +43,38 @@ namespace cocoon explicit MeasurementBase(Adopt adopt); /** * @brief Calls `-[NSMeasurement canBeConvertedToUnit:]`. - * @details Returns a Boolean value that indicates whether this measurement can be converted to the given unit. + * @details Given an NSUnit object, canBeConvertedToUnit: will check for dimensionality i.e. check the unit type (NSUnitAngle, NSUnitLength, NSUnitCustom, etc.) of the NSUnit object. It will return YES if the unit type of the given unit is the same as the unit type of the unit within the NSMeasurement object and NO if not. Note: This method will return NO if given or called on a dimensionless unit. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool can_be_converted_to_unit(const Unit& unit) const; /** * @brief Calls `-[NSMeasurement measurementByAddingMeasurement:]`. - * @details Returns a new measurement by adding the receiver to the given measurement. - Parameter measurement: The measurement to add. Must be of the same dimensionality as the receiver. - Returns: A new 'NSMeasurement' with the adjusted value and the same unit as the receiver. + * @details Given an NSMeasurement object, these methods will first check for dimensionality i.e. check the unit type (NSUnitAngle, NSUnitLength, NSUnitCustom, etc.) of the unit contained in that object. If the unit type of the unit in the given NSMeasurement object is not the same as the unit type of the unit within the current NSMeasurement instance (i.e. the units are of differing dimensionalities), these methods will throw an InvalidArgumentException. \@return A new NSMeasurement object with the adjusted value and a unit that is the same type as the current NSMeasurement instance. * @param measurement Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ MeasurementBase measurement_by_adding_measurement(const MeasurementBase& measurement) const; /** * @brief Calls `-[NSMeasurement measurementByConvertingToUnit:]`. - * @details Returns a measurement created by converting the receiver to the specified unit. - Parameter unit: The unit to convert to. Must be of the same dimensionality as the receiver's unit. - Returns: A new 'NSMeasurement' object with the given unit and converted value. + * @details Given an NSUnit object, measurementByConvertingUnit: will first check for dimensionality i.e. check the unit type (NSUnitAngle, NSUnitLength, NSUnitCustom, etc.) of the NSUnit object. If the unit type of the given unit is not the same as the unit type of the unit within the NSMeasurement object (i.e. the units are of differing dimensionalities), measurementByConvertingToUnit: will throw an InvalidArgumentException. \@return A new NSMeasurement object with the given unit and converted value. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ MeasurementBase measurement_by_converting_to_unit(const Unit& unit) const; /** * @brief Calls `-[NSMeasurement measurementBySubtractingMeasurement:]`. - * @details Returns a new measurement by subtracting the given measurement from the receiver. - Parameter measurement: The measurement to subtract. Must be of the same dimensionality as the receiver. - Returns: A new 'NSMeasurement' with the adjusted value and the same unit as the receiver. * @param measurement Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ MeasurementBase measurement_by_subtracting_measurement(const MeasurementBase& measurement) const; /** * @brief Returns the `doubleValue` property of `NSMeasurement`. - * @details The value component of the measurement. * @return The converted Objective-C result. */ double double_value() const; /** * @brief Returns the `unit` property of `NSMeasurement`. - * @details The unit component of the measurement. * @return The converted Objective-C result. */ Object unit() const; diff --git a/include/generated/measurement_formatter.h b/include/generated/measurement_formatter.h index 9da6f8a5..4b2d1328 100644 --- a/include/generated/measurement_formatter.h +++ b/include/generated/measurement_formatter.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMeasurementFormatter` (Foundation). - * @details A formatter that provides localized representations of units and measurements. You use the ''string(from:)-wt9y'' method to create a localized representation of an ''NSMeasurement'' object, and you use the ''string(from:)-4hwjz'' method to create a localized representation of an ''Unit'' object. The formatter takes into account the specified ''locale'', ''unitStyle'', and ''unitOptions'' when producing string representations of units and measurements. > Tip: > In Swift, you can use ''Measurement/FormatStyle'' rather than ''MeasurementFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -52,63 +51,62 @@ namespace cocoon explicit MeasurementFormatter(Adopt adopt); /** * @brief Calls `-[NSMeasurementFormatter stringFromMeasurement:]`. - * @details Creates and returns a localized string representation of the provided measurement. - Parameters: - measurement: The measurement to be represented. - Returns: A user-readable string that represents the measurement. * @param measurement Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_measurement(const MeasurementBase& measurement) const; /** * @brief Calls `-[NSMeasurementFormatter stringFromUnit:]`. - * @details Creates and returns a localized string representation of the provided unit of measure. If the unit cannot be localized, the unit's 'symbol' value is used. - Parameters: - unit: The unit of measure to be represented. - Returns: A user-readable string that represents the unit of measure. + * @details \@param An NSUnit \@return A formatted string representing the localized form of the unit without a value attached to it. This method will return [unit symbol] if the provided unit cannot be localized. * @param unit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_unit(const Unit& unit) const; /** * @brief Returns the `locale` property of `NSMeasurementFormatter`. - * @details The locale used when formatting measurements. If not specified, the locale is set to the user's current locale. + * @details If not specified, locale is set to the user's current locale. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSMeasurementFormatter`. - * @details The locale used when formatting measurements. If not specified, the locale is set to the user's current locale. + * @details If not specified, locale is set to the user's current locale. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; /** * @brief Returns the `numberFormatter` property of `NSMeasurementFormatter`. - * @details The number formatter used to format the numeric value of a measurement. If not specified, the number formatter is set up with 'NSNumberFormatterDecimalStyle'. + * @details If not specified, the number formatter is set up with NSNumberFormatterDecimalStyle. * @return The converted Objective-C result. */ NumberFormatter number_formatter() const; /** * @brief Sets the `numberFormatter` property of `NSMeasurementFormatter`. - * @details The number formatter used to format the numeric value of a measurement. If not specified, the number formatter is set up with 'NSNumberFormatterDecimalStyle'. + * @details If not specified, the number formatter is set up with NSNumberFormatterDecimalStyle. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_number_formatter(const NumberFormatter& value) const; /** * @brief Returns the `unitOptions` property of `NSMeasurementFormatter`. - * @details The options for how the unit is formatted. This property can be set to ensure that the formatter behaves in a way the developer expects, even if it is not standard according to the preferences of the user's locale. If not specified, 'unitOptions' defaults to localizing according to the preferences of the locale. Note that 'NSMeasurementFormatter' will handle converting measurement objects to the preferred units in a particular locale. For instance, if provided a measurement object in kilometers and the set locale is en_US, the formatter will implicitly convert the measurement object to miles and return the formatted string as the equivalent measurement in miles. + * @details This property can be set to ensure that the formatter behaves in a way the developer expects, even if it is not standard according to the preferences of the user's locale. If not specified, unitOptions defaults to localizing according to the preferences of the locale. Ex: By default, if unitOptions is set to the empty set, the formatter will do the following: - kilocalories may be formatted as "C" instead of "kcal" depending on the locale. - kilometersPerHour may be formatted as "miles per hour" for US and UK locales but "kilometers per hour" for other locales. However, if NSMeasurementFormatterUnitOptionsProvidedUnit is set, the formatter will do the following: - kilocalories would be formatted as "kcal" in the language of the locale, even if the locale prefers "C". - kilometersPerHour would be formatted as "kilometers per hour" for US and UK locales even though the preference is for "miles per hour." Note that NSMeasurementFormatter will handle converting measurement objects to the preferred units in a particular locale. For instance, if provided a measurement object in kilometers and the set locale is en_US, the formatter will implicitly convert the measurement object to miles and return the formatted string as the equivalent measurement in miles. * @return The converted Objective-C result. */ MeasurementFormatterUnitOptions unit_options() const; /** * @brief Sets the `unitOptions` property of `NSMeasurementFormatter`. - * @details The options for how the unit is formatted. This property can be set to ensure that the formatter behaves in a way the developer expects, even if it is not standard according to the preferences of the user's locale. If not specified, 'unitOptions' defaults to localizing according to the preferences of the locale. Note that 'NSMeasurementFormatter' will handle converting measurement objects to the preferred units in a particular locale. For instance, if provided a measurement object in kilometers and the set locale is en_US, the formatter will implicitly convert the measurement object to miles and return the formatted string as the equivalent measurement in miles. + * @details This property can be set to ensure that the formatter behaves in a way the developer expects, even if it is not standard according to the preferences of the user's locale. If not specified, unitOptions defaults to localizing according to the preferences of the locale. Ex: By default, if unitOptions is set to the empty set, the formatter will do the following: - kilocalories may be formatted as "C" instead of "kcal" depending on the locale. - kilometersPerHour may be formatted as "miles per hour" for US and UK locales but "kilometers per hour" for other locales. However, if NSMeasurementFormatterUnitOptionsProvidedUnit is set, the formatter will do the following: - kilocalories would be formatted as "kcal" in the language of the locale, even if the locale prefers "C". - kilometersPerHour would be formatted as "kilometers per hour" for US and UK locales even though the preference is for "miles per hour." Note that NSMeasurementFormatter will handle converting measurement objects to the preferred units in a particular locale. For instance, if provided a measurement object in kilometers and the set locale is en_US, the formatter will implicitly convert the measurement object to miles and return the formatted string as the equivalent measurement in miles. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_unit_options(MeasurementFormatterUnitOptions value) const; /** * @brief Returns the `unitStyle` property of `NSMeasurementFormatter`. - * @details The unit style used when creating string representations of measurements. If not specified, 'unitStyle' is set to 'NSFormattingUnitStyleMedium'. + * @details If not specified, unitStyle is set to NSFormattingUnitStyleMedium. * @return The converted Objective-C result. */ FormattingUnitStyle unit_style() const; /** * @brief Sets the `unitStyle` property of `NSMeasurementFormatter`. - * @details The unit style used when creating string representations of measurements. If not specified, 'unitStyle' is set to 'NSFormattingUnitStyleMedium'. + * @details If not specified, unitStyle is set to NSFormattingUnitStyleMedium. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_unit_style(FormattingUnitStyle value) const; diff --git a/include/generated/menu_item.h b/include/generated/menu_item.h index 58d1fb40..201d3270 100644 --- a/include/generated/menu_item.h +++ b/include/generated/menu_item.h @@ -173,13 +173,11 @@ namespace cocoon bool is_highlighted() const; /** * @brief Returns the `image` property of `NSMenuItem`. - * @details Set an image that is displayed next to the menu item's title. Note that in macOS 27 and later, AppKit determines the visibility of menu item images, and will typically hide images. Use the 'preferredImageVisibility' property with the '.visible' constant to specify that an image should always be visible. * @return The converted Objective-C result. */ Image image() const; /** * @brief Sets the `image` property of `NSMenuItem`. - * @details Set an image that is displayed next to the menu item's title. Note that in macOS 27 and later, AppKit determines the visibility of menu item images, and will typically hide images. Use the 'preferredImageVisibility' property with the '.visible' constant to specify that an image should always be visible. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_image(const Image& value) const; @@ -261,24 +259,6 @@ namespace cocoon * @return The converted Objective-C result. */ MenuItem parent_item() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `preferredImageVisibility` property of `NSMenuItem`. - * @details A menu item's image visibility determines whether the item's image is displayed when the menu is open. The default visibility for an item's image is Automatic. With this value, AppKit determines whether the item's image is visible based on system configuration. If an item's image should be visible in all cases, regardless of macOS version or other settings, then set the image visibility to '.visible'. - * @return The converted Objective-C result. - */ - MenuItemImageVisibility preferred_image_visibility() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `preferredImageVisibility` property of `NSMenuItem`. - * @details A menu item's image visibility determines whether the item's image is displayed when the menu is open. The default visibility for an item's image is Automatic. With this value, AppKit determines whether the item's image is visible based on system configuration. If an item's image should be visible in all cases, regardless of macOS version or other settings, then set the image visibility to '.visible'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_preferred_image_visibility(MenuItemImageVisibility value) const; -#endif - /** * @brief Returns the `representedObject` property of `NSMenuItem`. * @return The converted Objective-C result. diff --git a/include/generated/message_port.h b/include/generated/message_port.h index 899ec80d..eca7363a 100644 --- a/include/generated/message_port.h +++ b/include/generated/message_port.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSMessagePort` (Foundation). - * @details A port that can be used as an endpoint for distributed object connections (or raw messaging). ''MessagePort'' is a subclass of ''Port'' that allows for local (on the same machine) communication only. A companion class, ''SocketPort'', allows for both local and remote communication, but may be more expensive than ''MessagePort'' for the local case. ''MessagePort'' defines no additional methods over those already defined by ''Port''. > Note: > ''MessagePort'' conforms to the ''NSCoding'' protocol, but only supports coding by an ''NSPortCoder'' object. ''Port'' and its subclasses do not support archiving. > Important: > Avoid ''MessagePort''. There's little reason to use ''MessagePort'' rather than ''NSMachPort'' or ''SocketPort''. There's no particular performance or functionality advantage. It is recommended avoiding its use. > > ''MessagePort'' may be deprecated in the macOS 10.6 or later. \#\# See Also - [Distributed Objects Programming Topics](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DistrObjects/DistrObjects.html\#//apple_ref/doc/uid/10000102i) A port that can be used for local message sending on all platforms. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Port. * diff --git a/include/generated/message_port_name_server.h b/include/generated/message_port_name_server.h index 21d839a8..e3fb1363 100644 --- a/include/generated/message_port_name_server.h +++ b/include/generated/message_port_name_server.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMessagePortNameServer` (Foundation). - * @details \@DeprecationSummary { Use ''NSXPCConnection'' instead. } A server takes and returns message ports. This port name server takes and returns instances of ''MessagePort''. Port removal functionality is not supported in ''NSMessagePortNameServer''; if you want to cancel a service, you have to destroy the port (invalidate the ''MessagePort'' object given to ''NSPortNameServer/registerPort:name:''). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref PortNameServer. * @@ -44,14 +43,12 @@ namespace cocoon using PortNameServer::port_for_name; /** * @brief Calls `-[NSMessagePortNameServer portForName:]`. - * @details Looks up and returns the port registered under the specified name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Port port_for_name(const std::string& name) const; /** * @brief Calls `-[NSMessagePortNameServer portForName:host:]`. - * @details Looks up and returns the port registered under the specified name on a given host. This name server is a local-only server; the host parameter must be an empty string or 'nil'. * @param name Argument converted to the Objective-C parameter of the same role. * @param host Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -59,7 +56,6 @@ namespace cocoon Port port_for_name(const std::string& name, const std::string& host) const; /** * @brief Calls `+[NSMessagePortNameServer sharedInstance]`. - * @details Returns the shared instance of the message port name server. * @return The converted Objective-C result. */ static Object shared_instance(); diff --git a/include/generated/metadata_item.h b/include/generated/metadata_item.h index 7d10c9b9..26eea366 100644 --- a/include/generated/metadata_item.h +++ b/include/generated/metadata_item.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMetadataItem` (Foundation). - * @details The metadata associated with a file. Metadata items provide a simple interface to retrieve the available attribute names and values. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,21 +43,18 @@ namespace cocoon explicit MetadataItem(Adopt adopt); /** * @brief Calls `-[NSMetadataItem valueForAttribute:]`. - * @details Returns the value for the specified attribute of the receiver. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object value_for_attribute(const std::string& key) const; /** * @brief Calls `-[NSMetadataItem valuesForAttributes:]`. - * @details Returns a dictionary containing the specified attributes and their values. * @param keys Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map values_for_attributes(const std::vector& keys) const; /** * @brief Returns the `attributes` property of `NSMetadataItem`. - * @details An array containing the attributes of the receiver. * @return The converted Objective-C result. */ std::vector attributes() const; diff --git a/include/generated/metadata_query.h b/include/generated/metadata_query.h index d63def9e..7d946732 100644 --- a/include/generated/metadata_query.h +++ b/include/generated/metadata_query.h @@ -17,7 +17,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMetadataQuery` (Foundation). - * @details A query that you perform against Spotlight metadata. The ''NSMetadataQuery'' class encapsulates the functionality provided by the \ opaque type for querying the Spotlight metadata. ''NSMetadataQuery'' objects provide metadata query results in several ways: - As individual attribute values for requested attributes. - As value lists that contain the distinct values for given attributes in the query results. - As a result array proxy, containing all the query results. This is suitable for use with Cocoa bindings. - As a hierarchical collection of results, grouping together items with the same values for specified grouping attributes. This is also suitable for use with Cocoa bindings. Queries have two phases: the initial gathering phase that collects all currently matching results and a second live-update phase. By default, the receiver has no limitation on its search scope. Use the ''searchScopes'' property to customize. By default, notification of updated results occurs at 1.0 seconds. Use the ''notificationBatchingInterval'' property to customize. You must set a predicate with the ''predicate'' property before starting a query. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -55,55 +54,46 @@ namespace cocoon explicit MetadataQuery(Adopt adopt); /** * @brief Calls `-[NSMetadataQuery disableUpdates]`. - * @details Disables updates to the query results. These nest. */ void disable_updates() const; /** * @brief Calls `-[NSMetadataQuery enableUpdates]`. - * @details Enables updates to the query results. */ void enable_updates() const; /** * @brief Calls `-[NSMetadataQuery enumerateResultsUsingBlock:]`. - * @details Enumerates the current set of results using the given block. This method disables the query at the start of the iteration and reenables it upon completion. * @param block Argument converted to the Objective-C parameter of the same role. */ void enumerate_results_using_block(std::function block) const; /** * @brief Calls `-[NSMetadataQuery enumerateResultsWithOptions:usingBlock:]`. - * @details Enumerates the current set of results using the given block and enumeration options. * @param opts Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. */ void enumerate_results_with_options(EnumerationOptions opts, std::function block) const; /** * @brief Calls `-[NSMetadataQuery indexOfResult:]`. - * @details Returns the index of the specified result. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::uint64_t index_of_result(const Object& result) const; /** * @brief Calls `-[NSMetadataQuery resultAtIndex:]`. - * @details Returns the query result at a specific index. For performance reasons, use this method when retrieving a specific result, rather than the array returned by the results property. * @param idx Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object result_at_index(std::uint64_t idx) const; /** * @brief Calls `-[NSMetadataQuery startQuery]`. - * @details Attempts to start the query. Returns YES when successful; otherwise, NO. A query may fail to start if it does not specify a predicate, or if the query has already been started. This method must be called from the receiver's operationQueue or on the main thread. * @return The converted Objective-C result. */ bool start_query() const; /** * @brief Calls `-[NSMetadataQuery stopQuery]`. - * @details Stops the query from generating any further results. */ void stop_query() const; /** * @brief Calls `-[NSMetadataQuery valueOfAttribute:forResultAtIndex:]`. - * @details Returns the value for the attribute name attrName at the index in the results specified by idx. The attribute must be specified in valueListAttributes, as a sorting key in a specified sort descriptor, or as one of the grouping attributes specified for the query. * @param attr_name Argument converted to the Objective-C parameter of the same role. * @param idx Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -111,139 +101,116 @@ namespace cocoon Object value_of_attribute(const std::string& attr_name, std::uint64_t idx) const; /** * @brief Returns the `gathering` property of `NSMetadataQuery`. - * @details A Boolean value that indicates whether the query is in its initial gathering phase. * @return The converted Objective-C result. */ bool is_gathering() const; /** * @brief Returns the `groupedResults` property of `NSMetadataQuery`. - * @details An array of NSMetadataQueryResultGroups, for the first grouping attribute. * @return The converted Objective-C result. */ std::vector grouped_results() const; /** * @brief Returns the `groupingAttributes` property of `NSMetadataQuery`. - * @details An array of attributes used to group query results. * @return The converted Objective-C result. */ std::vector grouping_attributes() const; /** * @brief Sets the `groupingAttributes` property of `NSMetadataQuery`. - * @details An array of attributes used to group query results. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_grouping_attributes(const std::vector& value) const; /** * @brief Returns the `notificationBatchingInterval` property of `NSMetadataQuery`. - * @details The interval at which notification of updated results occurs. * @return The converted Objective-C result. */ double notification_batching_interval() const; /** * @brief Sets the `notificationBatchingInterval` property of `NSMetadataQuery`. - * @details The interval at which notification of updated results occurs. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_notification_batching_interval(double value) const; /** * @brief Returns the `operationQueue` property of `NSMetadataQuery`. - * @details An optional operation queue for notifications and delegate method calls. * @return The converted Objective-C result. */ OperationQueue operation_queue() const; /** * @brief Sets the `operationQueue` property of `NSMetadataQuery`. - * @details An optional operation queue for notifications and delegate method calls. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_operation_queue(const OperationQueue& value) const; /** * @brief Returns the `predicate` property of `NSMetadataQuery`. - * @details The predicate used to filter query results. Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query. * @return The converted Objective-C result. */ Predicate predicate() const; /** * @brief Sets the `predicate` property of `NSMetadataQuery`. - * @details The predicate used to filter query results. Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_predicate(const Predicate& value) const; /** * @brief Returns the `resultCount` property of `NSMetadataQuery`. - * @details The number of results returned by the query. * @return The converted Objective-C result. */ std::uint64_t result_count() const; /** * @brief Returns the `results` property of `NSMetadataQuery`. - * @details An array containing the query's results. This is for key-value bindings, and causes side-effects on the query. * @return The converted Objective-C result. */ std::vector results() const; /** * @brief Returns the `searchItems` property of `NSMetadataQuery`. - * @details An array of objects that the query will search. Items can be a mixture of NSMetadataItem, NSURL objects (file URLs only) and/or string paths; the getter returns the same mixture as was set. * @return The converted Objective-C result. */ std::vector search_items() const; /** * @brief Sets the `searchItems` property of `NSMetadataQuery`. - * @details An array of objects that the query will search. Items can be a mixture of NSMetadataItem, NSURL objects (file URLs only) and/or string paths; the getter returns the same mixture as was set. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_search_items(const std::vector& value) const; /** * @brief Returns the `searchScopes` property of `NSMetadataQuery`. - * @details An array of search scopes that limits where the query searches for results. Scopes is an NSArray of NSURL objects (file URLs only) and/or string paths and/or the special string constants below, which specifies the locations to which the search is limited; an empty array means no limits, which is the default state. * @return The converted Objective-C result. */ std::vector search_scopes() const; /** * @brief Sets the `searchScopes` property of `NSMetadataQuery`. - * @details An array of search scopes that limits where the query searches for results. Scopes is an NSArray of NSURL objects (file URLs only) and/or string paths and/or the special string constants below, which specifies the locations to which the search is limited; an empty array means no limits, which is the default state. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_search_scopes(const std::vector& value) const; /** * @brief Returns the `sortDescriptors` property of `NSMetadataQuery`. - * @details An array of sort descriptors to use when sorting the query results. * @return The converted Objective-C result. */ std::vector sort_descriptors() const; /** * @brief Sets the `sortDescriptors` property of `NSMetadataQuery`. - * @details An array of sort descriptors to use when sorting the query results. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_sort_descriptors(const std::vector& value) const; /** * @brief Returns the `started` property of `NSMetadataQuery`. - * @details A Boolean value that indicates whether the query has started. * @return The converted Objective-C result. */ bool is_started() const; /** * @brief Returns the `stopped` property of `NSMetadataQuery`. - * @details A Boolean value that indicates whether the query has been stopped. * @return The converted Objective-C result. */ bool is_stopped() const; /** * @brief Returns the `valueListAttributes` property of `NSMetadataQuery`. - * @details An array of attributes whose values are gathered by the query. * @return The converted Objective-C result. */ std::vector value_list_attributes() const; /** * @brief Sets the `valueListAttributes` property of `NSMetadataQuery`. - * @details An array of attributes whose values are gathered by the query. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_value_list_attributes(const std::vector& value) const; /** * @brief Returns the `valueLists` property of `NSMetadataQuery`. - * @details A dictionary containing arrays of attribute value tuples, keyed by attribute name. Values are arrays of 'NSMetadataQueryAttributeValueTuple'. * @return The converted Objective-C result. */ std::map> value_lists() const; diff --git a/include/generated/metadata_query_attribute_value_tuple.h b/include/generated/metadata_query_attribute_value_tuple.h index 022a2f62..2ee767c5 100644 --- a/include/generated/metadata_query_attribute_value_tuple.h +++ b/include/generated/metadata_query_attribute_value_tuple.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSMetadataQueryAttributeValueTuple` (Foundation). - * @details The 'NSMetadataQueryAttributeValueTuple' class represents attribute-value tuples, which are objects that contain the attribute name and value of a metadata attribute. Attribute-value tuples are returned by 'NSMetadataQuery' objects as the results in the value lists. Each attribute/value tuple contains the attribute name, the value, and the number of instances of that value that exist for the attribute name. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -32,19 +31,16 @@ namespace cocoon explicit MetadataQueryAttributeValueTuple(Adopt adopt); /** * @brief Returns the `attribute` property of `NSMetadataQueryAttributeValueTuple`. - * @details The attribute name for the tuple. * @return The converted Objective-C result. */ std::string attribute() const; /** * @brief Returns the `count` property of `NSMetadataQueryAttributeValueTuple`. - * @details The number of results with the given attribute value. * @return The converted Objective-C result. */ std::uint64_t count() const; /** * @brief Returns the `value` property of `NSMetadataQueryAttributeValueTuple`. - * @details The attribute value for the tuple. * @return The converted Objective-C result. */ Object value() const; diff --git a/include/generated/metadata_query_result_group.h b/include/generated/metadata_query_result_group.h index 2edf5f93..e3e0463c 100644 --- a/include/generated/metadata_query_result_group.h +++ b/include/generated/metadata_query_result_group.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSMetadataQueryResultGroup` (Foundation). - * @details The 'NSMetadataQueryResultGroup' class represents a collection of grouped attribute results returned by an ''NSMetadataQuery'' object. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -39,38 +38,32 @@ namespace cocoon explicit MetadataQueryResultGroup(Adopt adopt); /** * @brief Calls `-[NSMetadataQueryResultGroup resultAtIndex:]`. - * @details Returns the result at the specified index within this group. * @param idx Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object result_at_index(std::uint64_t idx) const; /** * @brief Returns the `attribute` property of `NSMetadataQueryResultGroup`. - * @details The attribute name for this result group. * @return The converted Objective-C result. */ std::string attribute() const; /** * @brief Returns the `resultCount` property of `NSMetadataQueryResultGroup`. - * @details The number of results in this group. * @return The converted Objective-C result. */ std::uint64_t result_count() const; /** * @brief Returns the `results` property of `NSMetadataQueryResultGroup`. - * @details An array containing the results in this group. This is for K-V Bindings, and causes side-effects on the query. * @return The converted Objective-C result. */ std::vector results() const; /** * @brief Returns the `subgroups` property of `NSMetadataQueryResultGroup`. - * @details An array of subgroups for this result group, or nil if this is a leaf group. * @return The converted Objective-C result. */ std::vector subgroups() const; /** * @brief Returns the `value` property of `NSMetadataQueryResultGroup`. - * @details The attribute value for this result group. * @return The converted Objective-C result. */ Object value() const; diff --git a/include/generated/method_signature.h b/include/generated/method_signature.h index 3571d7d4..3f85982e 100644 --- a/include/generated/method_signature.h +++ b/include/generated/method_signature.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSMethodSignature` (Foundation). - * @details A record of the type information for the return value and parameters of a method. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -41,45 +40,38 @@ namespace cocoon explicit MethodSignature(Adopt adopt); /** * @brief Calls `-[NSMethodSignature getArgumentTypeAtIndex:]`. - * @details Returns the type encoding for the argument at a given index. * @param idx Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string get_argument_type_at_index(std::uint64_t idx) const; /** * @brief Calls `-[NSMethodSignature isOneway]`. - * @details Returns a Boolean value that indicates whether the receiver is asynchronous (the 'oneway' qualifier). * @return The converted Objective-C result. */ bool is_oneway() const; /** * @brief Calls `+[NSMethodSignature signatureWithObjCTypes:]`. - * @details Returns an ''NSMethodSignature'' object for the given Objective-C method type string. * @param types Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static MethodSignature signature_with_obj_c_types(const std::string& types); /** * @brief Returns the `frameLength` property of `NSMethodSignature`. - * @details The number of bytes required by the receiver to store its arguments on the stack frame. * @return The converted Objective-C result. */ std::uint64_t frame_length() const; /** * @brief Returns the `methodReturnLength` property of `NSMethodSignature`. - * @details The number of bytes required for the return value. * @return The converted Objective-C result. */ std::uint64_t method_return_length() const; /** * @brief Returns the `methodReturnType` property of `NSMethodSignature`. - * @details A C string encoding the return type of the method. * @return The converted Objective-C result. */ std::string method_return_type() const; /** * @brief Returns the `numberOfArguments` property of `NSMethodSignature`. - * @details The number of arguments recorded in the receiver. * @return The converted Objective-C result. */ std::uint64_t number_of_arguments() const; diff --git a/include/generated/morphology.h b/include/generated/morphology.h index 43370515..e1401a7f 100644 --- a/include/generated/morphology.h +++ b/include/generated/morphology.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSMorphology` (Foundation). - * @details A description of the grammatical properties of a string. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -75,13 +74,11 @@ namespace cocoon void set_grammatical_case(GrammaticalCase value) const; /** * @brief Returns the `grammaticalGender` property of `NSMorphology`. - * @details The grammatical gender used for inflecting strings. * @return The converted Objective-C result. */ GrammaticalGender grammatical_gender() const; /** * @brief Sets the `grammaticalGender` property of `NSMorphology`. - * @details The grammatical gender used for inflecting strings. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_grammatical_gender(GrammaticalGender value) const; @@ -97,25 +94,21 @@ namespace cocoon void set_grammatical_person(GrammaticalPerson value) const; /** * @brief Returns the `number` property of `NSMorphology`. - * @details The grammatical number used for inflecting strings. * @return The converted Objective-C result. */ GrammaticalNumber number() const; /** * @brief Sets the `number` property of `NSMorphology`. - * @details The grammatical number used for inflecting strings. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_number(GrammaticalNumber value) const; /** * @brief Returns the `partOfSpeech` property of `NSMorphology`. - * @details The grammatical part of speech used for inflecting strings. * @return The converted Objective-C result. */ GrammaticalPartOfSpeech part_of_speech() const; /** * @brief Sets the `partOfSpeech` property of `NSMorphology`. - * @details The grammatical part of speech used for inflecting strings. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_part_of_speech(GrammaticalPartOfSpeech value) const; @@ -131,13 +124,11 @@ namespace cocoon void set_pronoun_type(GrammaticalPronounType value) const; /** * @brief Returns the `unspecified` property of `NSMorphology`. - * @details A Boolean value that indicates whether the morphology has no specific settings. * @return The converted Objective-C result. */ bool is_unspecified() const; /** * @brief Returns the `userMorphology` property of `NSMorphology`. - * @details The current user's morphology. * @return The converted Objective-C result. */ static Morphology user_morphology(); diff --git a/include/generated/morphology_custom_pronoun.h b/include/generated/morphology_custom_pronoun.h index 93ca1cb4..b4f57cd6 100644 --- a/include/generated/morphology_custom_pronoun.h +++ b/include/generated/morphology_custom_pronoun.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSMorphologyCustomPronoun` (Foundation). - * @details A custom pronoun behavior for use in a specific language. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,75 +44,63 @@ namespace cocoon explicit MorphologyCustomPronoun(Adopt adopt); /** * @brief Calls `+[NSMorphologyCustomPronoun isSupportedForLanguage:]`. - * @details Returns a Boolean value that indicates whether custom pronouns are supported for the specified language. * @param language Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool is_supported_for_language(const std::string& language); /** * @brief Calls `+[NSMorphologyCustomPronoun requiredKeysForLanguage:]`. - * @details Returns the list of pronoun form keys required for the specified language. * @param language Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector required_keys_for_language(const std::string& language); /** * @brief Returns the `objectForm` property of `NSMorphologyCustomPronoun`. - * @details The object pronoun form. * @return The converted Objective-C result. */ std::string object_form() const; /** * @brief Sets the `objectForm` property of `NSMorphologyCustomPronoun`. - * @details The object pronoun form. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_object_form(const std::string& value) const; /** * @brief Returns the `possessiveAdjectiveForm` property of `NSMorphologyCustomPronoun`. - * @details The possessive adjective form. * @return The converted Objective-C result. */ std::string possessive_adjective_form() const; /** * @brief Sets the `possessiveAdjectiveForm` property of `NSMorphologyCustomPronoun`. - * @details The possessive adjective form. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_possessive_adjective_form(const std::string& value) const; /** * @brief Returns the `possessiveForm` property of `NSMorphologyCustomPronoun`. - * @details The possessive pronoun form. * @return The converted Objective-C result. */ std::string possessive_form() const; /** * @brief Sets the `possessiveForm` property of `NSMorphologyCustomPronoun`. - * @details The possessive pronoun form. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_possessive_form(const std::string& value) const; /** * @brief Returns the `reflexiveForm` property of `NSMorphologyCustomPronoun`. - * @details The reflexive pronoun form. * @return The converted Objective-C result. */ std::string reflexive_form() const; /** * @brief Sets the `reflexiveForm` property of `NSMorphologyCustomPronoun`. - * @details The reflexive pronoun form. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_reflexive_form(const std::string& value) const; /** * @brief Returns the `subjectForm` property of `NSMorphologyCustomPronoun`. - * @details The subject pronoun form. * @return The converted Objective-C result. */ std::string subject_form() const; /** * @brief Sets the `subjectForm` property of `NSMorphologyCustomPronoun`. - * @details The subject pronoun form. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_subject_form(const std::string& value) const; diff --git a/include/generated/move_command.h b/include/generated/move_command.h index 68477e33..c3aeb5ee 100644 --- a/include/generated/move_command.h +++ b/include/generated/move_command.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMoveCommand` (Foundation). - * @details A command that moves one or more scriptable objects. An instance of 'NSMoveCommand' moves the specified scriptable object or objects; for example, it may move words to a new location in a document or a file to a new directory. 'NSMoveCommand' is part of Cocoa's built-in scripting support. It works automatically to support the 'move' AppleScript command through key-value coding. Most applications don't need to subclass 'NSMoveCommand' or invoke its methods. However, for circumstances where you might choose to subclass this command, see "Modifying a Standard Command" in [Script Commands](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_script_cmds/SAppsScriptCmds.html\#//apple_ref/doc/uid/20001242) in [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html\#//apple_ref/doc/uid/TP40002164). When an instance of 'NSMoveCommand' is executed, it does not make copies of moved objects. It removes objects from the source container or containers, then inserts them into the destination container. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptCommand. * @@ -43,13 +42,11 @@ namespace cocoon using ScriptCommand::set_receivers_specifier; /** * @brief Calls `-[NSMoveCommand setReceiversSpecifier:]`. - * @details Splits off the inner-most child specifier from the receivers specifier. * @param receivers_ref Argument converted to the Objective-C parameter of the same role. */ void set_receivers_specifier(const ScriptObjectSpecifier& receivers_ref) const; /** * @brief Returns the `keySpecifier` property of `NSMoveCommand`. - * @details The key specifier for the move operation. * @return The converted Objective-C result. */ ScriptObjectSpecifier key_specifier() const; diff --git a/include/generated/mutable_attributed_string.h b/include/generated/mutable_attributed_string.h index ce1133e2..81abf08c 100644 --- a/include/generated/mutable_attributed_string.h +++ b/include/generated/mutable_attributed_string.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMutableAttributedString` (Foundation). - * @details A mutable string with associated attributes (such as visual style, hyperlinks, or accessibility data) for portions of its text. The 'NSMutableAttributedString' class declares additional methods for mutating the content of an attributed string. You can add and remove characters (raw strings) and attributes separately or together as attributed strings. See the class description for ''NSAttributedString'' for more information about attributed strings. 'NSMutableAttributedString' adds two primitive methods to those of 'NSAttributedString'. These primitive methods provide the basis for all the other methods in its class. The primitive ''replaceCharacters(in:with:)-6oq9r'' method replaces a range of characters with those from a string, leaving all attribute information outside that range intact. The primitive ''setAttributes(:range:)'' method sets attributes and values for a given range of characters, replacing any previous attributes and values for that range. In macOS, AppKit also uses \ and its subclass \ to encapsulate the paragraph or ruler attributes used by the 'NSAttributedString' classes. Note that the default font for 'NSAttributedString' objects is Helvetica 12-point, which may differ from the macOS system font, so you may wish to create the string with non-default attributes suitable for your application using, for example, ''NSAttributedString/init(string:attributes:)''. > iOS Note: > In iOS, this class is used primarily in conjunction with the Core Text framework. 'NSMutableAttributedString' is "toll-free bridged" with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref AttributedString. * @@ -45,7 +44,6 @@ namespace cocoon explicit MutableAttributedString(Adopt adopt); /** * @brief Calls `-[NSMutableAttributedString addAttribute:value:range:]`. - * @details Adds an attribute with the given name and value to the characters in the specified range. You may assign any 'name'/'value' pair you wish to a range of characters. Raises an 'NSInvalidArgumentException' if 'name' or 'value' is 'nil' and an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. - Parameters: - name: A string specifying the attribute name. - value: The attribute value associated with 'name'. - range: The range of characters to which the specified attribute/value pair applies. * @param name Argument converted to the Objective-C parameter of the same role. * @param value Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -53,14 +51,12 @@ namespace cocoon void add_attribute(const std::string& name, const Object& value, const Range& range) const; /** * @brief Calls `-[NSMutableAttributedString addAttributes:range:]`. - * @details Adds the given collection of attributes to the characters in the specified range. You may assign any name/value pair you wish to a range of characters. Raises an 'NSInvalidArgumentException' if 'attrs' is 'nil' and an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. - Parameters: - attrs: A dictionary containing the attributes to add. - range: The range of characters to which the specified attributes apply. * @param attrs Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. */ void add_attributes(const std::map& attrs, const Range& range) const; /** * @brief Calls `-[NSMutableAttributedString appendAttributedString:]`. - * @details Adds the characters and attributes of a given attributed string to the end of the receiver. - Parameter attrString: The string whose characters and attributes are added. * @param attr_string Argument converted to the Objective-C parameter of the same role. */ void append_attributed_string(const AttributedString& attr_string) const; @@ -72,18 +68,15 @@ namespace cocoon void apply_font_traits(FontTraitMask trait_mask, const Range& range) const; /** * @brief Calls `-[NSMutableAttributedString beginEditing]`. - * @details Begins the buffering of changes to the string's characters and attributes. Override this method in a subclass to buffer or optimize a series of changes to the string's characters or attributes. The string continues to buffer text until you call 'endEditing', at which time it consolidates the changes and notifies observers. You can nest pairs of 'beginEditing' and 'endEditing' messages. */ void begin_editing() const; /** * @brief Calls `-[NSMutableAttributedString deleteCharactersInRange:]`. - * @details Deletes the characters in the given range along with their associated attributes. Raises an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. - Parameter range: A range specifying the characters to delete. * @param range Argument converted to the Objective-C parameter of the same role. */ void delete_characters_in_range(const Range& range) const; /** * @brief Calls `-[NSMutableAttributedString endEditing]`. - * @details Ends the buffering of changes to the string's characters and attributes. Override this method in a subclass to consolidate changes made since a previous call to 'beginEditing'. When you call this method, the string notifies observers of the changes. The default implementation of this method does nothing. */ void end_editing() const; /** @@ -108,7 +101,6 @@ namespace cocoon void fix_paragraph_style_attribute_in_range(const Range& range) const; /** * @brief Calls `-[NSMutableAttributedString insertAttributedString:atIndex:]`. - * @details Inserts the characters and attributes of the given attributed string into the receiver at the given index. The new characters and attributes begin at the given index and the existing characters and attributes from the index to the end of the receiver are shifted by the length of the attributed string. Raises an 'NSRangeException' if 'loc' lies beyond the end of the receiver's characters. - Parameters: - attrString: The string whose characters and attributes are inserted. - loc: The index at which the characters and attributes are inserted. * @param attr_string Argument converted to the Objective-C parameter of the same role. * @param loc Argument converted to the Objective-C parameter of the same role. */ @@ -131,21 +123,18 @@ namespace cocoon bool read_from_url(const URL& url, const std::map& opts, std::map& dict) const; /** * @brief Calls `-[NSMutableAttributedString removeAttribute:range:]`. - * @details Removes the named attribute from the characters in the specified range. Raises an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. - Parameters: - name: A string specifying the attribute name to remove. - range: The range of characters from which the specified attribute is removed. * @param name Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. */ void remove_attribute(const std::string& name, const Range& range) const; /** * @brief Calls `-[NSMutableAttributedString replaceCharactersInRange:withAttributedString:]`. - * @details Replaces the characters and attributes in a given range with the characters and attributes of the given attributed string. Raises an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. - Parameters: - range: The range of characters and attributes replaced. - attrString: The attributed string whose characters and attributes replace those in the specified range. * @param range Argument converted to the Objective-C parameter of the same role. * @param attr_string Argument converted to the Objective-C parameter of the same role. */ void replace_characters_in_range(const Range& range, const AttributedString& attr_string) const; /** * @brief Calls `-[NSMutableAttributedString replaceCharactersInRange:withString:]`. - * @details Replaces the characters in the given range with the characters of the given string. The new characters inherit the attributes of the first replaced character from 'range'. Where the length of 'range' is 0, the new characters inherit the attributes of the character preceding 'range' if it has any, otherwise of the character following 'range'. Raises an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. - Parameters: - range: A range specifying the characters to replace. - str: A string specifying the characters to replace those in 'range'. * @param range Argument converted to the Objective-C parameter of the same role. * @param str Argument converted to the Objective-C parameter of the same role. */ @@ -158,13 +147,11 @@ namespace cocoon void set_alignment(TextAlignment alignment, const Range& range) const; /** * @brief Calls `-[NSMutableAttributedString setAttributedString:]`. - * @details Replaces the receiver's entire contents with the characters and attributes of the given attributed string. - Parameter attrString: The attributed string whose characters and attributes replace those in the receiver. * @param attr_string Argument converted to the Objective-C parameter of the same role. */ void set_attributed_string(const AttributedString& attr_string) const; /** * @brief Calls `-[NSMutableAttributedString setAttributes:range:]`. - * @details Sets the attributes for the characters in the specified range to the specified attributes. These new attributes replace any attributes previously associated with the characters in 'range'. Raises an 'NSRangeException' if any part of 'range' lies beyond the end of the receiver's characters. - Parameters: - attrs: A dictionary containing the attributes to set. - range: The range of characters whose attributes are set. * @param attrs Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. */ @@ -197,7 +184,6 @@ namespace cocoon void update_attachments_from_path(const std::string& path) const; /** * @brief Returns the `mutableString` property of `NSMutableAttributedString`. - * @details The character contents of the receiver as a mutable string object. The receiver tracks changes to this string and keeps its attribute mappings up to date. * @return The converted Objective-C result. */ std::string mutable_string() const; diff --git a/include/generated/mutable_character_set.h b/include/generated/mutable_character_set.h index a6a76f45..4007bcf4 100644 --- a/include/generated/mutable_character_set.h +++ b/include/generated/mutable_character_set.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMutableCharacterSet` (Foundation). - * @details An object representing a mutable set of Unicode character values for use in search operations. In Swift, this object bridges to ''CharacterSet''; use ''NSMutableCharacterSet'' when you need reference semantics or other Foundation-specific behavior. The 'NSMutableCharacterSet' class declares the programmatic interface to objects that manage a modifiable set of Unicode characters. You can add or remove characters from a mutable character set as numeric values in 'NSRange' structures or as character values in strings, combine character sets by union or intersection, and invert a character set. Mutable character sets are less efficient to use than immutable character sets. If you don't need to change a character set after creating it, create an immutable copy with 'copy' and use that. 'NSMutableCharacterSet' defines no primitive methods. Subclasses must implement all methods declared by this class in addition to the primitives of ''NSCharacterSet''. They must also implement ''NSMutableCopying/mutableCopy(with:)''. 'NSMutableCharacterSet' is "toll-free bridged" with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information. > Important: > The Swift overlay to the Foundation framework provides the ''CharacterSet'' structure, which bridges to the ''NSMutableCharacterSet'' class and its immutable superclass, ''NSCharacterSet''. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref CharacterSet. * @@ -61,160 +60,134 @@ namespace cocoon using CharacterSet::whitespace_character_set; /** * @brief Calls `-[NSMutableCharacterSet addCharactersInRange:]`. - * @details Adds to the receiver the characters whose Unicode values are in a given range. This code excerpt adds to a character set the lowercase English alphabetic characters: '''objc NSMutableCharacterSet aCharacterSet = [[NSMutableCharacterSet alloc] init]; NSRange lcEnglishRange; lcEnglishRange.location = (unsigned int)'a'; lcEnglishRange.length = 26; [aCharacterSet addCharactersInRange:lcEnglishRange]; ''' - Parameter aRange: The range of characters to add. 'aRange.location' is the value of the first character to add; 'aRange.location + aRange.length - 1' is the value of the last. If 'aRange.length' is '0', this method has no effect. * @param a_range Argument converted to the Objective-C parameter of the same role. */ void add_characters_in_range(const Range& a_range) const; /** * @brief Calls `-[NSMutableCharacterSet addCharactersInString:]`. - * @details Adds to the receiver the characters in a given string. This method has no effect if 'aString' is empty. - Parameter aString: The characters to add to the receiver. * @param a_string Argument converted to the Objective-C parameter of the same role. */ void add_characters_in_string(const std::string& a_string) const; /** * @brief Calls `+[NSMutableCharacterSet alphanumericCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Categories L\\, M\\, and N\\. * @return The converted Objective-C result. */ static MutableCharacterSet alphanumeric_character_set(); /** * @brief Calls `+[NSMutableCharacterSet capitalizedLetterCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category Lt. * @return The converted Objective-C result. */ static MutableCharacterSet capitalized_letter_character_set(); /** * @brief Calls `+[NSMutableCharacterSet characterSetWithBitmapRepresentation:]`. - * @details Returns a mutable character set containing characters determined by a given bitmap representation. * @param data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static MutableCharacterSet character_set_with_bitmap_representation(const std::vector& data); /** * @brief Calls `+[NSMutableCharacterSet characterSetWithCharactersInString:]`. - * @details Returns a mutable character set containing the characters in a given string. * @param a_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static MutableCharacterSet character_set_with_characters_in_string(const std::string& a_string); /** * @brief Calls `+[NSMutableCharacterSet characterSetWithContentsOfFile:]`. - * @details Returns a mutable character set read from the bitmap representation stored in the file at a given path. * @param f_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static MutableCharacterSet character_set_with_contents_of_file(const std::string& f_name); /** * @brief Calls `+[NSMutableCharacterSet characterSetWithRange:]`. - * @details Returns a mutable character set containing characters with Unicode values in a given range. * @param a_range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static MutableCharacterSet character_set_with_range(const Range& a_range); /** * @brief Calls `+[NSMutableCharacterSet controlCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category Cc and Cf. * @return The converted Objective-C result. */ static MutableCharacterSet control_character_set(); /** * @brief Calls `+[NSMutableCharacterSet decimalDigitCharacterSet]`. - * @details Returns a mutable character set containing the characters in the category of decimal numbers. * @return The converted Objective-C result. */ static MutableCharacterSet decimal_digit_character_set(); /** * @brief Calls `+[NSMutableCharacterSet decomposableCharacterSet]`. - * @details Returns a mutable character set containing individual Unicode characters that can also be represented as composed character sequences (such as for letters with accents), by the definition of "standard decomposition" in version 3.2 of the Unicode character encoding standard. * @return The converted Objective-C result. */ static MutableCharacterSet decomposable_character_set(); /** * @brief Calls `-[NSMutableCharacterSet formIntersectionWithCharacterSet:]`. - * @details Modifies the receiver so it contains only characters that exist in both the receiver and another set. - Parameter otherSet: The character set with which to perform the intersection. * @param other_set Argument converted to the Objective-C parameter of the same role. */ void form_intersection_with_character_set(const CharacterSet& other_set) const; /** * @brief Calls `-[NSMutableCharacterSet formUnionWithCharacterSet:]`. - * @details Modifies the receiver so it contains all characters that exist in either the receiver or another set. * @param other_set Argument converted to the Objective-C parameter of the same role. */ void form_union_with_character_set(const CharacterSet& other_set) const; /** * @brief Calls `+[NSMutableCharacterSet illegalCharacterSet]`. - * @details Returns a mutable character set containing values in the category of Non-Characters or that have not yet been defined in version 3.2 of the Unicode standard. * @return The converted Objective-C result. */ static MutableCharacterSet illegal_character_set(); /** * @brief Calls `-[NSMutableCharacterSet invert]`. - * @details Replaces all the characters in the receiver with all the characters it didn't previously contain. Inverting a mutable character set, whether by 'invert' or by 'invertedSet', is much less efficient than inverting an immutable character set with 'invertedSet'. */ void invert() const; /** * @brief Calls `+[NSMutableCharacterSet letterCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category L\\ & M\\. * @return The converted Objective-C result. */ static MutableCharacterSet letter_character_set(); /** * @brief Calls `+[NSMutableCharacterSet lowercaseLetterCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category Ll. * @return The converted Objective-C result. */ static MutableCharacterSet lowercase_letter_character_set(); /** * @brief Calls `+[NSMutableCharacterSet newlineCharacterSet]`. - * @details Returns a mutable character set containing the newline characters ('U+000A' ~ 'U+000D', 'U+0085', 'U+2028', and 'U+2029'). * @return The converted Objective-C result. */ static MutableCharacterSet newline_character_set(); /** * @brief Calls `+[NSMutableCharacterSet nonBaseCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category M\\. * @return The converted Objective-C result. */ static MutableCharacterSet non_base_character_set(); /** * @brief Calls `+[NSMutableCharacterSet punctuationCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category P\\. * @return The converted Objective-C result. */ static MutableCharacterSet punctuation_character_set(); /** * @brief Calls `-[NSMutableCharacterSet removeCharactersInRange:]`. - * @details Removes from the receiver the characters whose Unicode values are in a given range. - Parameter aRange: The range of characters to remove. 'aRange.location' is the value of the first character to remove; 'aRange.location + aRange.length - 1' is the value of the last. If 'aRange.length' is '0', this method has no effect. * @param a_range Argument converted to the Objective-C parameter of the same role. */ void remove_characters_in_range(const Range& a_range) const; /** * @brief Calls `-[NSMutableCharacterSet removeCharactersInString:]`. - * @details Removes from the receiver the characters in a given string. This method has no effect if 'aString' is empty. - Parameter aString: The characters to remove from the receiver. * @param a_string Argument converted to the Objective-C parameter of the same role. */ void remove_characters_in_string(const std::string& a_string) const; /** * @brief Calls `+[NSMutableCharacterSet symbolCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category S\\. * @return The converted Objective-C result. */ static MutableCharacterSet symbol_character_set(); /** * @brief Calls `+[NSMutableCharacterSet uppercaseLetterCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category Lu and Lt. * @return The converted Objective-C result. */ static MutableCharacterSet uppercase_letter_character_set(); /** * @brief Calls `+[NSMutableCharacterSet whitespaceAndNewlineCharacterSet]`. - * @details Returns a mutable character set containing characters in Unicode General Category Z\\, 'U+000A' ~ 'U+000D', and 'U+0085'. * @return The converted Objective-C result. */ static MutableCharacterSet whitespace_and_newline_character_set(); /** * @brief Calls `+[NSMutableCharacterSet whitespaceCharacterSet]`. - * @details Returns a mutable character set containing the characters in Unicode General Category Zs and 'CHARACTER TABULATION' ('U+0009'). * @return The converted Objective-C result. */ static MutableCharacterSet whitespace_character_set(); diff --git a/include/generated/mutable_index_set.h b/include/generated/mutable_index_set.h index 36bab0ee..39769b49 100644 --- a/include/generated/mutable_index_set.h +++ b/include/generated/mutable_index_set.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMutableIndexSet` (Foundation). - * @details A mutable collection of unique integer values that represent indexes in another collection. In Swift, this type bridges to ''IndexSet''; use ''NSMutableIndexSet'' when you need reference semantics or other Foundation-specific behavior. The ''NSMutableIndexSet'' class represents a mutable collection of unique unsigned integers, known as indexes because of the way they are used. This collection is referred to as a mutable index set. The inclusive range of valid indexes is '0...(NSNotFound - 1)'; trying to use indexes outside this range is invalid. The values in a mutable index set are always sorted, so the order in which values are added is irrelevant. Do not subclass the ''NSMutableIndexSet'' class. > Important: > The Swift overlay to the Foundation framework provides the ''IndexSet'' structure, which bridges to the ''NSMutableIndexSet'' class and its immutable superclass, ''NSIndexSet''. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref IndexSet. * @@ -44,48 +43,41 @@ namespace cocoon explicit MutableIndexSet(Adopt adopt); /** * @brief Calls `-[NSMutableIndexSet addIndex:]`. - * @details Adds an index to the receiver. - Parameter value: Index to add. Must be in the range '0 .. NSNotFound - 1'. * @param value Argument converted to the Objective-C parameter of the same role. */ void add_index(std::uint64_t value) const; /** * @brief Calls `-[NSMutableIndexSet addIndexes:]`. - * @details Adds the indexes in an index set to the receiver. - Parameter indexSet: Index set to add. * @param index_set Argument converted to the Objective-C parameter of the same role. */ void add_indexes(const IndexSet& index_set) const; /** * @brief Calls `-[NSMutableIndexSet addIndexesInRange:]`. - * @details Adds the indexes in an index range to the receiver. This method raises an 'NSRangeException' when 'range' would add an index that exceeds the maximum allowed value for unsigned integers. - Parameter range: Index range to add. Must be in the range '0 .. NSNotFound - 1'. * @param range Argument converted to the Objective-C parameter of the same role. */ void add_indexes_in_range(const Range& range) const; /** * @brief Calls `-[NSMutableIndexSet removeAllIndexes]`. - * @details Removes the receiver's indexes. */ void remove_all_indexes() const; /** * @brief Calls `-[NSMutableIndexSet removeIndex:]`. - * @details Removes an index from the receiver. - Parameter value: Index to remove. * @param value Argument converted to the Objective-C parameter of the same role. */ void remove_index(std::uint64_t value) const; /** * @brief Calls `-[NSMutableIndexSet removeIndexes:]`. - * @details Removes the indexes in an index set from the receiver. - Parameter indexSet: Index set to remove. * @param index_set Argument converted to the Objective-C parameter of the same role. */ void remove_indexes(const IndexSet& index_set) const; /** * @brief Calls `-[NSMutableIndexSet removeIndexesInRange:]`. - * @details Removes the indexes in an index range from the receiver. - Parameter range: Index range to remove. * @param range Argument converted to the Objective-C parameter of the same role. */ void remove_indexes_in_range(const Range& range) const; /** * @brief Calls `-[NSMutableIndexSet shiftIndexesStartingAtIndex:by:]`. - * @details Shifts a group of indexes to the left or the right within the receiver. The group of indexes shifted is made up by 'index' and the indexes that follow it in the set. A left shift deletes the indexes in a range the length of 'delta' preceding 'index' from the set. A right shift inserts empty space in the range '(index, delta)' in the receiver. The resulting indexes must all be in the range '0 .. NSNotFound - 1'. - Parameters: - index: Head of the group of indexes to shift. - delta: Amount and direction of the shift. Positive integers shift the indexes to the right. Negative integers shift the indexes to the left. + * @details For a positive delta, shifts the indexes in [index, INT_MAX] to the right, thereby inserting an "empty space" [index, delta], for a negative delta, shifts the indexes in [index, INT_MAX] to the left, thereby deleting the indexes in the range [index - delta, delta]. * @param index Argument converted to the Objective-C parameter of the same role. * @param delta Argument converted to the Objective-C parameter of the same role. */ diff --git a/include/generated/mutable_paragraph_style.h b/include/generated/mutable_paragraph_style.h index 91d2e378..e49eb7fa 100644 --- a/include/generated/mutable_paragraph_style.h +++ b/include/generated/mutable_paragraph_style.h @@ -9,7 +9,6 @@ namespace cocoon { class ParagraphStyle; - class TextBlock; class TextList; class TextTab; @@ -23,19 +22,19 @@ namespace cocoon * #include * * cocoon::MutableParagraphStyle mutable_paragraph_style; - * mutable_paragraph_style.set_alignment(cocoon::TextAlignment::Left); + * mutable_paragraph_style.set_allows_default_tightening_for_truncation(true); * @endcode * * @par Common tasks * Snippets built from this class's own members (values are placeholders). * @code * cocoon::MutableParagraphStyle mutable_paragraph_style{}; - * mutable_paragraph_style.set_alignment(cocoon::TextAlignment::Left); - * auto alignment = mutable_paragraph_style.alignment(); * mutable_paragraph_style.set_allows_default_tightening_for_truncation(true); * auto allows_default_tightening_for_truncation = mutable_paragraph_style.allows_default_tightening_for_truncation(); * mutable_paragraph_style.set_base_writing_direction(cocoon::WritingDirection::Natural); * auto base_writing_direction = mutable_paragraph_style.base_writing_direction(); + * mutable_paragraph_style.set_default_tab_interval(1); + * auto default_tab_interval = mutable_paragraph_style.default_tab_interval(); * mutable_paragraph_style.add_tab_stop(cocoon::TextTab()); * mutable_paragraph_style.remove_tab_stop(cocoon::TextTab()); * mutable_paragraph_style.set_paragraph_style(cocoon::ParagraphStyle()); @@ -51,13 +50,11 @@ namespace cocoon MutableParagraphStyle(std::nullptr_t); /// @brief Wraps an existing retained native object without creating a new one. explicit MutableParagraphStyle(Adopt adopt); - using ParagraphStyle::alignment; using ParagraphStyle::allows_default_tightening_for_truncation; using ParagraphStyle::base_writing_direction; using ParagraphStyle::default_tab_interval; using ParagraphStyle::first_line_head_indent; using ParagraphStyle::head_indent; - using ParagraphStyle::header_level; using ParagraphStyle::hyphenation_factor; using ParagraphStyle::line_break_mode; using ParagraphStyle::line_break_strategy; @@ -69,289 +66,200 @@ namespace cocoon using ParagraphStyle::paragraph_spacing_before; using ParagraphStyle::tab_stops; using ParagraphStyle::tail_indent; - using ParagraphStyle::text_blocks; using ParagraphStyle::text_lists; - using ParagraphStyle::tightening_factor_for_truncation; using ParagraphStyle::uses_default_hyphenation; /** * @brief Calls `-[NSMutableParagraphStyle addTabStop:]`. - * @details Adds the specified tab stop to the paragraph. \#\# See Also - ''tabStops'' * @param an_object Argument converted to the Objective-C parameter of the same role. */ void add_tab_stop(const TextTab& an_object) const; /** * @brief Calls `-[NSMutableParagraphStyle removeTabStop:]`. - * @details Removes the first text tab with a location and type equal to the specified tab stop. \#\# See Also - ''tabStops'' * @param an_object Argument converted to the Objective-C parameter of the same role. */ void remove_tab_stop(const TextTab& an_object) const; /** * @brief Calls `-[NSMutableParagraphStyle setParagraphStyle:]`. - * @details Replaces the subattributes of the paragraph with those in the specified paragraph style object. * @param obj Argument converted to the Objective-C parameter of the same role. */ void set_paragraph_style(const ParagraphStyle& obj) const; - /** - * @brief Returns the `alignment` property of `NSMutableParagraphStyle`. - * @details The text alignment of the paragraph. - * @return The converted Objective-C result. - */ - TextAlignment alignment() const; - /** - * @brief Sets the `alignment` property of `NSMutableParagraphStyle`. - * @details The text alignment of the paragraph. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_alignment(TextAlignment value) const; /** * @brief Returns the `allowsDefaultTighteningForTruncation` property of `NSMutableParagraphStyle`. - * @details A Boolean value that indicates whether the system tightens intercharacter spacing before truncating text. When this property is set to \, the system tries to reduce the space between characters before truncating characters. The system performs this tightening in cases where the text would not otherwise fit in the available space. The maximum amount of tightening performed by the system is dependent on the font, line width, and other factors. The default value of this property is \. * @return The converted Objective-C result. */ bool allows_default_tightening_for_truncation() const; /** * @brief Sets the `allowsDefaultTighteningForTruncation` property of `NSMutableParagraphStyle`. - * @details A Boolean value that indicates whether the system tightens intercharacter spacing before truncating text. When this property is set to \, the system tries to reduce the space between characters before truncating characters. The system performs this tightening in cases where the text would not otherwise fit in the available space. The maximum amount of tightening performed by the system is dependent on the font, line width, and other factors. The default value of this property is \. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_default_tightening_for_truncation(bool value) const; /** * @brief Returns the `baseWritingDirection` property of `NSMutableParagraphStyle`. - * @details The base writing direction for the paragraph. If you specify ''NSWritingDirection/natural'', the consumer of the value must resolve the writing direction based on the paragraph contents using the Unicode Bidi Algorithm. * @return The converted Objective-C result. */ WritingDirection base_writing_direction() const; /** * @brief Sets the `baseWritingDirection` property of `NSMutableParagraphStyle`. - * @details The base writing direction for the paragraph. If you specify ''NSWritingDirection/natural'', the consumer of the value must resolve the writing direction based on the paragraph contents using the Unicode Bidi Algorithm. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_base_writing_direction(WritingDirection value) const; /** * @brief Returns the `defaultTabInterval` property of `NSMutableParagraphStyle`. - * @details A number used as the document's default tab spacing. This property represents the default tab interval in points. The system places tabs after the last specified in ''tabStops'' at integer multiples of this distance (if positive). Default value is '0.0'. * @return The converted Objective-C result. */ double default_tab_interval() const; /** * @brief Sets the `defaultTabInterval` property of `NSMutableParagraphStyle`. - * @details A number used as the document's default tab spacing. This property represents the default tab interval in points. The system places tabs after the last specified in ''tabStops'' at integer multiples of this distance (if positive). Default value is '0.0'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_default_tab_interval(double value) const; /** * @brief Returns the `firstLineHeadIndent` property of `NSMutableParagraphStyle`. - * @details The indentation of the first line of the paragraph. This property contains the distance (in points) from the leading margin of a text container to the beginning of the paragraph's first line. This value is always nonnegative. * @return The converted Objective-C result. */ double first_line_head_indent() const; /** * @brief Sets the `firstLineHeadIndent` property of `NSMutableParagraphStyle`. - * @details The indentation of the first line of the paragraph. This property contains the distance (in points) from the leading margin of a text container to the beginning of the paragraph's first line. This value is always nonnegative. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_first_line_head_indent(double value) const; /** * @brief Returns the `headIndent` property of `NSMutableParagraphStyle`. - * @details The indentation of the paragraph's lines other than the first. This property contains the distance (in points) from the leading margin of a text container to the beginning of lines other than the first. This value is always nonnegative. * @return The converted Objective-C result. */ double head_indent() const; /** * @brief Sets the `headIndent` property of `NSMutableParagraphStyle`. - * @details The indentation of the paragraph's lines other than the first. This property contains the distance (in points) from the leading margin of a text container to the beginning of lines other than the first. This value is always nonnegative. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_head_indent(double value) const; - /** - * @brief Returns the `headerLevel` property of `NSMutableParagraphStyle`. - * @details The paragraph's header level for HTML generation. Should be set to '0' (the default value) if the paragraph is not a header, or from 1 through 6 if the paragraph is to be treated as a header. - * @return The converted Objective-C result. - */ - std::int64_t header_level() const; - /** - * @brief Sets the `headerLevel` property of `NSMutableParagraphStyle`. - * @details The paragraph's header level for HTML generation. Should be set to '0' (the default value) if the paragraph is not a header, or from 1 through 6 if the paragraph is to be treated as a header. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_header_level(std::int64_t value) const; /** * @brief Returns the `hyphenationFactor` property of `NSMutableParagraphStyle`. - * @details The paragraph's threshold for hyphenation. Valid values lie between '0.0' and '1.0' inclusive. The default value is '0.0'. Hyphenation is attempted when the ratio of the text width (as broken without hyphenation) to the width of the line fragment is less than the hyphenation factor. When the paragraph's hyphenation factor is '0.0', the text layout manager's hyphenation factor is used instead. When both are '0.0', hyphenation is disabled. This property detects the user-selected language by examining the first item in 'preferredLanguages'. \#\# See Also - \ * @return The converted Objective-C result. */ float hyphenation_factor() const; /** * @brief Sets the `hyphenationFactor` property of `NSMutableParagraphStyle`. - * @details The paragraph's threshold for hyphenation. Valid values lie between '0.0' and '1.0' inclusive. The default value is '0.0'. Hyphenation is attempted when the ratio of the text width (as broken without hyphenation) to the width of the line fragment is less than the hyphenation factor. When the paragraph's hyphenation factor is '0.0', the text layout manager's hyphenation factor is used instead. When both are '0.0', hyphenation is disabled. This property detects the user-selected language by examining the first item in 'preferredLanguages'. \#\# See Also - \ * @param value Argument converted to the Objective-C parameter of the same role. */ void set_hyphenation_factor(float value) const; /** * @brief Returns the `lineBreakMode` property of `NSMutableParagraphStyle`. - * @details The mode for breaking lines in the paragraph. This property controls how the text system lays out lines that don't fit in its container, such as by truncating with an ellipsis (…) or clipping the text. This is different from ''NSParagraphStyle/LineBreakStrategy'', which controls where the system places line breaks in a paragraph. * @return The converted Objective-C result. */ LineBreakMode line_break_mode() const; /** * @brief Sets the `lineBreakMode` property of `NSMutableParagraphStyle`. - * @details The mode for breaking lines in the paragraph. This property controls how the text system lays out lines that don't fit in its container, such as by truncating with an ellipsis (…) or clipping the text. This is different from ''NSParagraphStyle/LineBreakStrategy'', which controls where the system places line breaks in a paragraph. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_line_break_mode(LineBreakMode value) const; /** * @brief Returns the `lineBreakStrategy` property of `NSMutableParagraphStyle`. - * @details The strategies that the text system may use to break lines while laying out the paragraph. Line-break strategies are collections of options the system uses to determine where to break lines in a paragraph. This is different from ''NSParagraphStyle/lineBreakMode'', which controls how to lay out lines of text that don't fit in a container. The system ignores this property if the paragraph style's ''NSParagraphStyle/lineBreakMode'' property specifies a mode that doesn't support multiple lines, such as ''NSLineBreakMode/byClipping''. The default value is ''NSLineBreakStrategy/NSLineBreakStrategyNone''. * @return The converted Objective-C result. */ LineBreakStrategy line_break_strategy() const; /** * @brief Sets the `lineBreakStrategy` property of `NSMutableParagraphStyle`. - * @details The strategies that the text system may use to break lines while laying out the paragraph. Line-break strategies are collections of options the system uses to determine where to break lines in a paragraph. This is different from ''NSParagraphStyle/lineBreakMode'', which controls how to lay out lines of text that don't fit in a container. The system ignores this property if the paragraph style's ''NSParagraphStyle/lineBreakMode'' property specifies a mode that doesn't support multiple lines, such as ''NSLineBreakMode/byClipping''. The default value is ''NSLineBreakStrategy/NSLineBreakStrategyNone''. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_line_break_strategy(LineBreakStrategy value) const; /** * @brief Returns the `lineHeightMultiple` property of `NSMutableParagraphStyle`. - * @details The line height multiple. The natural line height of the receiver is multiplied by this factor (if positive) before being constrained by minimum and maximum line height. The default value of this property is '0.0'. * @return The converted Objective-C result. */ double line_height_multiple() const; /** * @brief Sets the `lineHeightMultiple` property of `NSMutableParagraphStyle`. - * @details The line height multiple. The natural line height of the receiver is multiplied by this factor (if positive) before being constrained by minimum and maximum line height. The default value of this property is '0.0'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_line_height_multiple(double value) const; /** * @brief Returns the `lineSpacing` property of `NSMutableParagraphStyle`. - * @details The distance in points between the bottom of one line fragment and the top of the next. This value is always nonnegative. This value is included in the line fragment heights in the text layout manager. * @return The converted Objective-C result. */ double line_spacing() const; /** * @brief Sets the `lineSpacing` property of `NSMutableParagraphStyle`. - * @details The distance in points between the bottom of one line fragment and the top of the next. This value is always nonnegative. This value is included in the line fragment heights in the text layout manager. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_line_spacing(double value) const; /** * @brief Returns the `maximumLineHeight` property of `NSMutableParagraphStyle`. - * @details The paragraph's maximum line height. This property contains the maximum height in points that any line in the receiver will occupy, regardless of the font size or size of any attached graphic. This value is always nonnegative. The default value is '0'. Glyphs and graphics exceeding this height will overlap neighboring lines; however, a maximum height of '0' implies no line height limit. Although this limit applies to the line itself, line spacing adds extra space between adjacent lines. * @return The converted Objective-C result. */ double maximum_line_height() const; /** * @brief Sets the `maximumLineHeight` property of `NSMutableParagraphStyle`. - * @details The paragraph's maximum line height. This property contains the maximum height in points that any line in the receiver will occupy, regardless of the font size or size of any attached graphic. This value is always nonnegative. The default value is '0'. Glyphs and graphics exceeding this height will overlap neighboring lines; however, a maximum height of '0' implies no line height limit. Although this limit applies to the line itself, line spacing adds extra space between adjacent lines. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum_line_height(double value) const; /** * @brief Returns the `minimumLineHeight` property of `NSMutableParagraphStyle`. - * @details The paragraph's minimum line height. This property contains the minimum height in points that any line in the receiver will occupy, regardless of the font size or size of any attached graphic. This value must be nonnegative. * @return The converted Objective-C result. */ double minimum_line_height() const; /** * @brief Sets the `minimumLineHeight` property of `NSMutableParagraphStyle`. - * @details The paragraph's minimum line height. This property contains the minimum height in points that any line in the receiver will occupy, regardless of the font size or size of any attached graphic. This value must be nonnegative. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minimum_line_height(double value) const; /** * @brief Returns the `paragraphSpacing` property of `NSMutableParagraphStyle`. - * @details The space after the end of the paragraph. This property contains the space (measured in points) added at the end of the paragraph to separate it from the following paragraph. This value must be nonnegative. The space between paragraphs is determined by adding the previous paragraph's 'paragraphSpacing' and the current paragraph's ''NSMutableParagraphStyle/paragraphSpacingBefore''. * @return The converted Objective-C result. */ double paragraph_spacing() const; /** * @brief Sets the `paragraphSpacing` property of `NSMutableParagraphStyle`. - * @details The space after the end of the paragraph. This property contains the space (measured in points) added at the end of the paragraph to separate it from the following paragraph. This value must be nonnegative. The space between paragraphs is determined by adding the previous paragraph's 'paragraphSpacing' and the current paragraph's ''NSMutableParagraphStyle/paragraphSpacingBefore''. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_paragraph_spacing(double value) const; /** * @brief Returns the `paragraphSpacingBefore` property of `NSMutableParagraphStyle`. - * @details The distance between the paragraph's top and the beginning of its text content. This property contains the space (measured in points) between the paragraph's top and the beginning of its text content. The default value of this property is '0.0'. * @return The converted Objective-C result. */ double paragraph_spacing_before() const; /** * @brief Sets the `paragraphSpacingBefore` property of `NSMutableParagraphStyle`. - * @details The distance between the paragraph's top and the beginning of its text content. This property contains the space (measured in points) between the paragraph's top and the beginning of its text content. The default value of this property is '0.0'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_paragraph_spacing_before(double value) const; /** * @brief Returns the `tabStops` property of `NSMutableParagraphStyle`. - * @details The text tab objects that represent the paragraph's tab stops. The ''NSTextTab'' objects, sorted by location, define the tab stops for the paragraph style. The default value is an array of 12 left-aligned tabs at 28-point intervals. * @return The converted Objective-C result. */ std::vector tab_stops() const; /** * @brief Sets the `tabStops` property of `NSMutableParagraphStyle`. - * @details The text tab objects that represent the paragraph's tab stops. The ''NSTextTab'' objects, sorted by location, define the tab stops for the paragraph style. The default value is an array of 12 left-aligned tabs at 28-point intervals. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tab_stops(const std::vector& value) const; /** * @brief Returns the `tailIndent` property of `NSMutableParagraphStyle`. - * @details The trailing indentation of the paragraph. If positive, this value is the distance from the leading margin (for example, the left margin in left-to-right text). If '0' or negative, it's the distance from the trailing margin. For example, a paragraph style designed to fit exactly in a 2-inch wide container has a head indent of '0.0' and a tail indent of '0.0'. One designed to fit with a quarter-inch margin has a head indent of '0.25' and a tail indent of '–0.25'. * @return The converted Objective-C result. */ double tail_indent() const; /** * @brief Sets the `tailIndent` property of `NSMutableParagraphStyle`. - * @details The trailing indentation of the paragraph. If positive, this value is the distance from the leading margin (for example, the left margin in left-to-right text). If '0' or negative, it's the distance from the trailing margin. For example, a paragraph style designed to fit exactly in a 2-inch wide container has a head indent of '0.0' and a tail indent of '0.0'. One designed to fit with a quarter-inch margin has a head indent of '0.25' and a tail indent of '–0.25'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tail_indent(double value) const; - /** - * @brief Returns the `textBlocks` property of `NSMutableParagraphStyle`. - * @details The text blocks that contain the paragraph. - * @return The converted Objective-C result. - */ - std::vector text_blocks() const; - /** - * @brief Sets the `textBlocks` property of `NSMutableParagraphStyle`. - * @details The text blocks that contain the paragraph. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_text_blocks(const std::vector& value) const; /** * @brief Returns the `textLists` property of `NSMutableParagraphStyle`. - * @details The text lists that contain the paragraph. * @return The converted Objective-C result. */ std::vector text_lists() const; /** * @brief Sets the `textLists` property of `NSMutableParagraphStyle`. - * @details The text lists that contain the paragraph. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_lists(const std::vector& value) const; - /** - * @brief Returns the `tighteningFactorForTruncation` property of `NSMutableParagraphStyle`. - * @details The threshold for using tightening as an alternative to truncation. When the line break mode specifies truncation, the text system will attempt to tighten inter-character spacing as an alternative to truncation, provided that the ratio of the text width to the line fragment width does not exceed '1.0 + tighteningFactorForTruncation'. Otherwise the text will be truncated at a location determined by the line break mode. The default value is '0.0' for apps linked against 10.11 and later SDK. This property is ignored when ''allowsDefaultTighteningForTruncation'' is 'true'. Explicitly setting this property to '0.0' has a side effect of also setting ''allowsDefaultTighteningForTruncation'' to 'false'. - * @return The converted Objective-C result. - */ - float tightening_factor_for_truncation() const; - /** - * @brief Sets the `tighteningFactorForTruncation` property of `NSMutableParagraphStyle`. - * @details The threshold for using tightening as an alternative to truncation. When the line break mode specifies truncation, the text system will attempt to tighten inter-character spacing as an alternative to truncation, provided that the ratio of the text width to the line fragment width does not exceed '1.0 + tighteningFactorForTruncation'. Otherwise the text will be truncated at a location determined by the line break mode. The default value is '0.0' for apps linked against 10.11 and later SDK. This property is ignored when ''allowsDefaultTighteningForTruncation'' is 'true'. Explicitly setting this property to '0.0' has a side effect of also setting ''allowsDefaultTighteningForTruncation'' to 'false'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_tightening_factor_for_truncation(float value) const; /** * @brief Returns the `usesDefaultHyphenation` property of `NSMutableParagraphStyle`. - * @details A Boolean value that indicates whether the paragraph style uses the system hyphenation settings. The system determines the exact hyphenation logic dynamically by examining the layout context such as language, platform, etc. When 'true', it affects the return value from ''hyphenationFactor'' when the property is set to '0.0'. * @return The converted Objective-C result. */ bool uses_default_hyphenation() const; /** * @brief Sets the `usesDefaultHyphenation` property of `NSMutableParagraphStyle`. - * @details A Boolean value that indicates whether the paragraph style uses the system hyphenation settings. The system determines the exact hyphenation logic dynamically by examining the layout context such as language, platform, etc. When 'true', it affects the return value from ''hyphenationFactor'' when the property is set to '0.0'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_uses_default_hyphenation(bool value) const; diff --git a/include/generated/mutable_url_request.h b/include/generated/mutable_url_request.h index f9a3b122..a32f9009 100644 --- a/include/generated/mutable_url_request.h +++ b/include/generated/mutable_url_request.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSMutableURLRequest` (Foundation). - * @details A mutable URL load request that is independent of protocol or URL scheme. In Swift, this object bridges to ''NSURLRequest'' and you use when you need reference semantics or other Foundation-specific behavior. ''NSMutableURLRequest'' is a subclass of ''NSURLRequest'' that allows you to change the request's properties. ''NSMutableURLRequest'' only represents information about the request. Use other classes, such as ''URLSession'', to send the request to a server. See \ and \ for an introduction to these techniques. Classes that create a network operation based on a request make a deep copy of that request. Thus, changing the request after creating a network operation has no effect on the ongoing operation. For example, if you use ''URLSession/dataTask(with:completionHandler:)-e6xv'' to create a data task from a request, and then later change the request, the data task continues using the original request. > Important: > The Swift overlay to the Foundation framework provides the ''URLRequest'' structure, which bridges to the ''NSMutableURLRequest'' class and its immutable superclass, ''NSURLRequest''. For more information about value types, see \. + * @details \@class NSMutableURLRequest \@abstract An NSMutableURLRequest object represents a mutable URL load request in a manner independent of protocol and URL scheme. \@discussion This specialization of NSURLRequest is provided to aid developers who may find it more convenient to mutate a single request object for a series of URL loads instead of creating an immutable NSURLRequest for each load. This programming model is supported by the following contract stipulation between NSMutableURLRequest and NSURLConnection: NSURLConnection makes a deep copy of each NSMutableURLRequest object passed to one of its initializers. \

NSMutableURLRequest is designed to be extended to support protocol-specific data by adding categories to access a property object provided in an interface targeted at protocol implementors. \

    \
  • Protocol implementors should direct their attention to the NSMutableURLRequestExtensibility category on NSMutableURLRequest for more information on how to provide extensions on NSMutableURLRequest to support protocol-specific request information. \
  • Clients of this API who wish to create NSMutableURLRequest objects to load URL content should consult the protocol-specific NSMutableURLRequest categories that are available. The NSMutableHTTPURLRequest category on NSMutableURLRequest is an example. \
* Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref URLRequest. * @@ -69,183 +69,183 @@ namespace cocoon using URLRequest::url; /** * @brief Calls `-[NSMutableURLRequest addValue:forHTTPHeaderField:]`. - * @details Adds an HTTP header field value to the current header dictionary. If a value was previously set for the given header field, the given value is appended to the previously-existing value. The appropriate field delimiter, a comma in the case of HTTP, is added by the implementation. In keeping with the HTTP RFC, HTTP header field names are case-insensitive. - Parameters: - value: The header field value. - field: The header field name (case-insensitive). + * @details \@method addValue:forHTTPHeaderField: \@abstract Adds an HTTP header field in the current header dictionary. \@discussion This method provides a way to add values to header fields incrementally. If a value was previously set for the given header field, the given value is appended to the previously-existing value. The appropriate field delimiter, a comma in the case of HTTP, is added by the implementation, and should not be added to the given value by the caller. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive. \@param value the header field value. \@param field the header field name (case-insensitive). * @param value Argument converted to the Objective-C parameter of the same role. * @param field Argument converted to the Objective-C parameter of the same role. */ void add_value(const std::string& value, const std::string& field) const; /** * @brief Calls `-[NSMutableURLRequest setValue:forHTTPHeaderField:]`. - * @details Sets the value of the given HTTP header field. If a value was previously set for the given header field, that value is replaced with the given value. In keeping with the HTTP RFC, HTTP header field names are case-insensitive. - Parameters: - value: The header field value. - field: The header field name (case-insensitive). + * @details \@method setValue:forHTTPHeaderField: \@abstract Sets the value of the given HTTP header field. \@discussion If a value was previously set for the given header field, that value is replaced with the given value. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive. \@param value the header field value. \@param field the header field name (case-insensitive). * @param value Argument converted to the Objective-C parameter of the same role. * @param field Argument converted to the Objective-C parameter of the same role. */ void set_value(const std::string& value, const std::string& field) const; /** * @brief Returns the `HTTPBody` property of `NSMutableURLRequest`. - * @details The request body data of the receiver. This data is sent as the message body of the request, as in done in an HTTP POST request. + * @details \@abstract Sets the request body data of the receiver. \@discussion This data is sent as the message body of the request, as in done in an HTTP POST request. * @return The converted Objective-C result. */ std::vector http_body() const; /** * @brief Sets the `HTTPBody` property of `NSMutableURLRequest`. - * @details The request body data of the receiver. This data is sent as the message body of the request, as in done in an HTTP POST request. + * @details \@abstract Sets the request body data of the receiver. \@discussion This data is sent as the message body of the request, as in done in an HTTP POST request. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_body(const std::vector& value) const; /** * @brief Returns the `HTTPBodyStream` property of `NSMutableURLRequest`. - * @details The request body stream of the receiver. The provided stream should be unopened; the request will take over the stream's delegate. The entire stream's contents will be transmitted as the HTTP body of the request. Note that the body stream and the body data (set by 'setHTTPBody:') are mutually exclusive - setting one will clear the other. + * @details \@abstract Sets the request body to be the contents of the given stream. \@discussion The provided stream should be unopened; the request will take over the stream's delegate. The entire stream's contents will be transmitted as the HTTP body of the request. Note that the body stream and the body data (set by setHTTPBody:, above) are mutually exclusive - setting one will clear the other. * @return The converted Objective-C result. */ InputStream http_body_stream() const; /** * @brief Sets the `HTTPBodyStream` property of `NSMutableURLRequest`. - * @details The request body stream of the receiver. The provided stream should be unopened; the request will take over the stream's delegate. The entire stream's contents will be transmitted as the HTTP body of the request. Note that the body stream and the body data (set by 'setHTTPBody:') are mutually exclusive - setting one will clear the other. + * @details \@abstract Sets the request body to be the contents of the given stream. \@discussion The provided stream should be unopened; the request will take over the stream's delegate. The entire stream's contents will be transmitted as the HTTP body of the request. Note that the body stream and the body data (set by setHTTPBody:, above) are mutually exclusive - setting one will clear the other. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_body_stream(const InputStream& value) const; /** * @brief Returns the `HTTPMethod` property of `NSMutableURLRequest`. - * @details The HTTP request method of the receiver. + * @details \@abstract Sets the HTTP request method of the receiver. * @return The converted Objective-C result. */ std::string http_method() const; /** * @brief Sets the `HTTPMethod` property of `NSMutableURLRequest`. - * @details The HTTP request method of the receiver. + * @details \@abstract Sets the HTTP request method of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_method(const std::string& value) const; /** * @brief Returns the `HTTPShouldHandleCookies` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether default cookie handling will happen for this request. The default is 'YES' - in other words, cookies are sent from and stored to the cookie manager by default. + * @details \@abstract Decide whether default cookie handling will happen for this request (YES if cookies should be sent with and set for this request; otherwise NO). \@discussion The default is YES - in other words, cookies are sent from and stored to the cookie manager by default. NOTE: In releases prior to 10.3, this value is ignored * @return The converted Objective-C result. */ bool http_should_handle_cookies() const; /** * @brief Sets the `HTTPShouldHandleCookies` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether default cookie handling will happen for this request. The default is 'YES' - in other words, cookies are sent from and stored to the cookie manager by default. + * @details \@abstract Decide whether default cookie handling will happen for this request (YES if cookies should be sent with and set for this request; otherwise NO). \@discussion The default is YES - in other words, cookies are sent from and stored to the cookie manager by default. NOTE: In releases prior to 10.3, this value is ignored * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_should_handle_cookies(bool value) const; /** * @brief Returns the `URL` property of `NSMutableURLRequest`. - * @details The URL of the receiver. + * @details \@abstract The URL of the receiver. * @return The converted Objective-C result. */ URL url() const; /** * @brief Sets the `URL` property of `NSMutableURLRequest`. - * @details The URL of the receiver. + * @details \@abstract The URL of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_url(const URL& value) const; /** * @brief Returns the `allHTTPHeaderFields` property of `NSMutableURLRequest`. - * @details The HTTP header fields of the receiver. Setting this property replaces all header fields that may have existed before this method call. Since HTTP header fields must be string values, each object and key in the dictionary must be an 'NSString'. + * @details \@abstract Sets the HTTP header fields of the receiver to the given dictionary. \@discussion This method replaces all header fields that may have existed before this method call. \

Since HTTP header fields must be string values, each object and key in the dictionary passed to this method must answer YES when sent an \-isKindOfClass:[NSString class]\ message. If either the key or value for a key-value pair answers NO when sent this message, the key-value pair is skipped. * @return The converted Objective-C result. */ std::map all_http_header_fields() const; /** * @brief Sets the `allHTTPHeaderFields` property of `NSMutableURLRequest`. - * @details The HTTP header fields of the receiver. Setting this property replaces all header fields that may have existed before this method call. Since HTTP header fields must be string values, each object and key in the dictionary must be an 'NSString'. + * @details \@abstract Sets the HTTP header fields of the receiver to the given dictionary. \@discussion This method replaces all header fields that may have existed before this method call. \

Since HTTP header fields must be string values, each object and key in the dictionary passed to this method must answer YES when sent an \-isKindOfClass:[NSString class]\ message. If either the key or value for a key-value pair answers NO when sent this message, the key-value pair is skipped. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_all_http_header_fields(const std::map& value) const; /** * @brief Returns the `allowsCellularAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use the built-in cellular radios (if present). The default is 'YES'. + * @details \@abstract sets whether a connection created with this request is allowed to use the built in cellular radios (if present). \@discussion NO if the receiver should not be allowed to use the built in cellular radios to satisfy the request, YES otherwise. The default is YES. * @return The converted Objective-C result. */ bool allows_cellular_access() const; /** * @brief Sets the `allowsCellularAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use the built-in cellular radios (if present). The default is 'YES'. + * @details \@abstract sets whether a connection created with this request is allowed to use the built in cellular radios (if present). \@discussion NO if the receiver should not be allowed to use the built in cellular radios to satisfy the request, YES otherwise. The default is YES. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_cellular_access(bool value) const; /** * @brief Returns the `allowsConstrainedNetworkAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as constrained. + * @details \@abstract sets whether a connection created with this request is allowed to use network interfaces which have been marked as constrained. \@discussion NO if the receiver should not be allowed to use an interface marked as constrained to satisfy the request, YES otherwise. * @return The converted Objective-C result. */ bool allows_constrained_network_access() const; /** * @brief Sets the `allowsConstrainedNetworkAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as constrained. + * @details \@abstract sets whether a connection created with this request is allowed to use network interfaces which have been marked as constrained. \@discussion NO if the receiver should not be allowed to use an interface marked as constrained to satisfy the request, YES otherwise. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_constrained_network_access(bool value) const; /** * @brief Returns the `allowsExpensiveNetworkAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as expensive. + * @details \@abstract sets whether a connection created with this request is allowed to use network interfaces which have been marked as expensive. \@discussion NO if the receiver should not be allowed to use an interface marked as expensive to satisfy the request, YES otherwise. * @return The converted Objective-C result. */ bool allows_expensive_network_access() const; /** * @brief Sets the `allowsExpensiveNetworkAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as expensive. + * @details \@abstract sets whether a connection created with this request is allowed to use network interfaces which have been marked as expensive. \@discussion NO if the receiver should not be allowed to use an interface marked as expensive to satisfy the request, YES otherwise. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_expensive_network_access(bool value) const; /** * @brief Returns the `allowsPersistentDNS` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether storing and usage of DNS answers in a persistent per-process cache is allowed. This should only be set for hostnames whose resolutions are not expected to change across networks. Defaults to 'NO'. + * @details \@abstract Allows storing and usage of DNS answers, potentially beyond TTL expiry, in a persistent per-process cache. This should only be set for hostnames whose resolutions are not expected to change across networks. \@discussion YES, if the DNS lookup for this request is allowed to use a persistent per-process cache, NO otherwise. Defaults to NO. * @return The converted Objective-C result. */ bool allows_persistent_dns() const; /** * @brief Sets the `allowsPersistentDNS` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether storing and usage of DNS answers in a persistent per-process cache is allowed. This should only be set for hostnames whose resolutions are not expected to change across networks. Defaults to 'NO'. + * @details \@abstract Allows storing and usage of DNS answers, potentially beyond TTL expiry, in a persistent per-process cache. This should only be set for hostnames whose resolutions are not expected to change across networks. \@discussion YES, if the DNS lookup for this request is allowed to use a persistent per-process cache, NO otherwise. Defaults to NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_persistent_dns(bool value) const; /** * @brief Returns the `allowsUltraConstrainedNetworkAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as ultra constrained. + * @details \@abstract sets whether a connection created with this request is allowed to use network interfaces which have been marked as ultra constrained. \@discussion NO if the receiver should not be allowed to use an interface marked as ultra constrained to satisfy the request, YES otherwise. * @return The converted Objective-C result. */ bool allows_ultra_constrained_network_access() const; /** * @brief Sets the `allowsUltraConstrainedNetworkAccess` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as ultra constrained. + * @details \@abstract sets whether a connection created with this request is allowed to use network interfaces which have been marked as ultra constrained. \@discussion NO if the receiver should not be allowed to use an interface marked as ultra constrained to satisfy the request, YES otherwise. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_ultra_constrained_network_access(bool value) const; /** * @brief Returns the `assumesHTTP3Capable` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether the server is assumed to support HTTP/3. When 'YES', enables QUIC racing without HTTP/3 service discovery. Defaults to 'NO'. The default may be 'YES' in a future OS update. + * @details \@abstract returns whether we assume that server supports HTTP/3. Enables QUIC racing without HTTP/3 service discovery. \@result YES if server endpoint is known to support HTTP/3. Defaults to NO. The default may be YES in a future OS update. * @return The converted Objective-C result. */ bool assumes_http3_capable() const; /** * @brief Sets the `assumesHTTP3Capable` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether the server is assumed to support HTTP/3. When 'YES', enables QUIC racing without HTTP/3 service discovery. Defaults to 'NO'. The default may be 'YES' in a future OS update. + * @details \@abstract returns whether we assume that server supports HTTP/3. Enables QUIC racing without HTTP/3 service discovery. \@result YES if server endpoint is known to support HTTP/3. Defaults to NO. The default may be YES in a future OS update. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_assumes_http3_capable(bool value) const; /** * @brief Returns the `attribution` property of `NSMutableURLRequest`. - * @details The 'NSURLRequestAttribution' to associate with this request. Set to 'NSURLRequestAttributionUser' if the URL was specified by the user. Defaults to 'NSURLRequestAttributionDeveloper'. + * @details \@abstract Sets the NSURLRequestAttribution to associate with this request. \@discussion Set to NSURLRequestAttributionUser if the URL was specified by the user. Defaults to NSURLRequestAttributionDeveloper. * @return The converted Objective-C result. */ URLRequestAttribution attribution() const; /** * @brief Sets the `attribution` property of `NSMutableURLRequest`. - * @details The 'NSURLRequestAttribution' to associate with this request. Set to 'NSURLRequestAttributionUser' if the URL was specified by the user. Defaults to 'NSURLRequestAttributionDeveloper'. + * @details \@abstract Sets the NSURLRequestAttribution to associate with this request. \@discussion Set to NSURLRequestAttributionUser if the URL was specified by the user. Defaults to NSURLRequestAttributionDeveloper. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attribution(URLRequestAttribution value) const; /** * @brief Returns the `cachePolicy` property of `NSMutableURLRequest`. - * @details The cache policy of the receiver. + * @details \@abstract The cache policy of the receiver. * @return The converted Objective-C result. */ URLRequestCachePolicy cache_policy() const; /** * @brief Sets the `cachePolicy` property of `NSMutableURLRequest`. - * @details The cache policy of the receiver. + * @details \@abstract The cache policy of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_cache_policy(URLRequestCachePolicy value) const; @@ -263,49 +263,49 @@ namespace cocoon void set_cookie_partition_identifier(const std::string& value) const; /** * @brief Returns the `mainDocumentURL` property of `NSMutableURLRequest`. - * @details The main document URL. The caller should pass the URL for an appropriate main document, if known. For example, when loading a web page, the URL of the main html document for the top-level frame should be passed. This main document is used to implement the cookie "only from same domain as main document" policy, attributing this request as a sub-resource of a user-specified URL, and possibly other things in the future. + * @details \@abstract Sets the main document URL \@discussion The caller should pass the URL for an appropriate main document, if known. For example, when loading a web page, the URL of the main html document for the top-level frame should be passed. This main document is used to implement the cookie "only from same domain as main document" policy, attributing this request as a sub-resource of a user-specified URL, and possibly other things in the future. * @return The converted Objective-C result. */ URL main_document_url() const; /** * @brief Sets the `mainDocumentURL` property of `NSMutableURLRequest`. - * @details The main document URL. The caller should pass the URL for an appropriate main document, if known. For example, when loading a web page, the URL of the main html document for the top-level frame should be passed. This main document is used to implement the cookie "only from same domain as main document" policy, attributing this request as a sub-resource of a user-specified URL, and possibly other things in the future. + * @details \@abstract Sets the main document URL \@discussion The caller should pass the URL for an appropriate main document, if known. For example, when loading a web page, the URL of the main html document for the top-level frame should be passed. This main document is used to implement the cookie "only from same domain as main document" policy, attributing this request as a sub-resource of a user-specified URL, and possibly other things in the future. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_main_document_url(const URL& value) const; /** * @brief Returns the `networkServiceType` property of `NSMutableURLRequest`. - * @details The 'NSURLRequestNetworkServiceType' to associate with this request. This is used to provide the network layers with a hint as to the purpose of the request. Most clients should not need to set this. + * @details \@abstract Sets the NSURLRequestNetworkServiceType to associate with this request \@discussion This method is used to provide the network layers with a hint as to the purpose of the request. Most clients should not need to use this method. * @return The converted Objective-C result. */ URLRequestNetworkServiceType network_service_type() const; /** * @brief Sets the `networkServiceType` property of `NSMutableURLRequest`. - * @details The 'NSURLRequestNetworkServiceType' to associate with this request. This is used to provide the network layers with a hint as to the purpose of the request. Most clients should not need to set this. + * @details \@abstract Sets the NSURLRequestNetworkServiceType to associate with this request \@discussion This method is used to provide the network layers with a hint as to the purpose of the request. Most clients should not need to use this method. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_network_service_type(URLRequestNetworkServiceType value) const; /** * @brief Returns the `requiresDNSSECValidation` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a request requires DNSSEC validation during DNS lookup. 'YES' if the DNS lookup for this request should require DNSSEC validation. Defaults to 'NO'. + * @details \@abstract sets whether a request is required to do DNSSEC validation during DNS lookup. \@discussion YES, if the DNS lookup for this request should require DNSSEC validation, No otherwise. Defaults to NO. * @return The converted Objective-C result. */ bool requires_dnssec_validation() const; /** * @brief Sets the `requiresDNSSECValidation` property of `NSMutableURLRequest`. - * @details A Boolean value that indicates whether a request requires DNSSEC validation during DNS lookup. 'YES' if the DNS lookup for this request should require DNSSEC validation. Defaults to 'NO'. + * @details \@abstract sets whether a request is required to do DNSSEC validation during DNS lookup. \@discussion YES, if the DNS lookup for this request should require DNSSEC validation, No otherwise. Defaults to NO. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_requires_dnssec_validation(bool value) const; /** * @brief Returns the `timeoutInterval` property of `NSMutableURLRequest`. - * @details The timeout interval of the receiver, measured in seconds. The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The "idle interval" is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. + * @details \@abstract Sets the timeout interval of the receiver. \@discussion The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The "idle interval" is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. This timeout interval is measured in seconds. * @return The converted Objective-C result. */ double timeout_interval() const; /** * @brief Sets the `timeoutInterval` property of `NSMutableURLRequest`. - * @details The timeout interval of the receiver, measured in seconds. The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The "idle interval" is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. + * @details \@abstract Sets the timeout interval of the receiver. \@discussion The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The "idle interval" is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. This timeout interval is measured in seconds. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_timeout_interval(double value) const; diff --git a/include/generated/name_specifier.h b/include/generated/name_specifier.h index 9e65b612..d01456ee 100644 --- a/include/generated/name_specifier.h +++ b/include/generated/name_specifier.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSNameSpecifier` (Foundation). - * @details A specifier for an object in a collection (or container) by name. As an example, the following script specifies both an application and a window by name. In this script, the named window's implicitly specified container is the Finder application's list of open windows. '''objc tell application "Finder" -- specifies an application by name close window "Reports" -- specifies a window by name end tell ''' This specifier works only for objects that have a name property. You don't normally subclass 'NSNameSpecifier'. The evaluation of an instance of 'NSNameSpecifier' follows these steps until the specified object is found: 1. If the container implements a method whose selector matches the relevant 'valueIn\WithName:' pattern established by scripting key-value coding, the method is invoked. This method can potentially be very fast, and it may be relatively easy to implement. 2. As is the case when evaluating any script object specifier, the container of the specified object is given a chance to evaluate the object specifier. If the container class implements the 'indicesOfObjectsByEvaluatingObjectSpecifier' method, the method is invoked. This method can potentially be very fast, but it is relatively difficult to implement. 3. An instance of 'NSWhoseSpecifier' that specifies the first object whose relevant ''pnam'' attribute matches the name is synthesized and evaluated. The instance of 'NSWhoseSpecifier' must search through all of the keyed elements in the container, looking for a match. The search is potentially very slow. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptObjectSpecifier. * @@ -47,13 +46,11 @@ namespace cocoon explicit NameSpecifier(Adopt adopt); /** * @brief Returns the `name` property of `NSNameSpecifier`. - * @details The name of the object to be retrieved. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSNameSpecifier`. - * @details The name of the object to be retrieved. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; diff --git a/include/generated/net_service.h b/include/generated/net_service.h index 3b14a1d5..69f1943a 100644 --- a/include/generated/net_service.h +++ b/include/generated/net_service.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSNetService` (Foundation). - * @details A network service that broadcasts its availability using multicast DNS. The ''NetService'' class represents a network service, either one your application publishes or is a client of. This class and the ''NetServiceBrowser'' class use multicast DNS to convey information about network services to and from your application. The API of ''NetService'' provides a convenient way to publish the services offered by your application and to resolve the socket address for a service. The types of services you access using ''NetService'' are the same types that you access directly using BSD sockets. HTTP and FTP are two services commonly provided by systems. (For a list of common services and the ports used by those services, see the file '/etc/services'.) Applications can also define their own custom services to provide specific data to clients. You can use the ''NetService'' class as either a publisher of a service or a client of a service. If your application publishes a service, your code must acquire a port and prepare a socket to communicate with clients. Once your socket is ready, you use the ''NetService'' class to notify clients that your service is ready. If your application is the client of a network service, you can either create an ''NetService'' object directly (if you know the exact host and port information) or use an ''NetServiceBrowser'' object to browse for services. To publish a service, initialize your ''NetService'' object with the service name, domain, type, and port information. All of this information must be valid for the socket created by your application. Once initialized, call the ''publish()'' method to broadcast your service information to the network. When connecting to a service, use the ''NetServiceBrowser'' class to locate the service on the network and obtain the corresponding ''NetService'' object. Once you have the object, call the ''resolve(withTimeout:)'' method to verify that the service is available and ready for your application. If it is, the ''addresses'' property provides the socket information you can use to connect to the service. The methods of ''NetService'' operate asynchronously so your application is not impacted by the speed of the network. All information about a service is returned to your application through the ''NetService'' object's delegate. You must provide a delegate object to respond to messages and to handle errors appropriately. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -57,27 +56,27 @@ namespace cocoon explicit NetService(Adopt adopt); /** * @brief Calls `-[NSNetService TXTRecordData]`. - * @details Returns the TXT record for the receiver. If the instance has not been resolved, or the delegate's '-netService:didUpdateTXTRecordData:' has not been called, this will return 'nil'. It is permitted to have a zero-length TXT record. + * @details Returns the raw TXT record of the NSNetService instance. If the instance has not been resolved, or the delegate's -netService:didUpdateTXTRecordData: has not been called, this will return nil. It is permitted to have a zero-length TXT record. * @return The converted Objective-C result. */ std::vector txt_record_data() const; /** * @brief Calls `+[NSNetService dataFromTXTRecordDictionary:]`. - * @details Returns an 'NSData' object representing a TXT record formed from a given dictionary. - Parameters: - txtDictionary: A dictionary containing a TXT record. - Returns: An 'NSData' object representing TXT data formed from 'txtDictionary'. Fails an assertion if 'txtDictionary' cannot be represented as an 'NSData' object. + * @details Returns an NSData created from the provided dictionary. The keys in the provided dictionary must be NSStrings, and the values must be NSDatas. If the dictionary cannot be converted into an NSData suitable for a TXT record, this method will return nil. For applications linked on or after Mac OS X 10.5, this method will throw an NSInvalidArgumentException if it is passed nil as the argument. * @param txt_dictionary Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector data_from_txt_record_dictionary(const std::map>& txt_dictionary); /** * @brief Calls `+[NSNetService dictionaryFromTXTRecordData:]`. - * @details Returns a dictionary representing a TXT record given as an 'NSData' object. - Parameters: - txtData: A data object encoding a TXT record. - Returns: A dictionary representing 'txtData'. The dictionary's keys are UTF8-encoded 'NSString' objects. The values associated with all the dictionary's keys are 'NSData' objects that encapsulate strings or data. Fails an assertion if 'txtData' cannot be represented as an 'NSDictionary' object. + * @details Returns an NSDictionary created from the provided NSData. The keys will be UTF8-encoded NSStrings. The values are NSDatas. The caller is responsible for interpreting these as types appropriate to the keys. If the NSData cannot be converted into an appropriate NSDictionary, this method will return nil. For applications linked on or after Mac OS X 10.5, this method will throw an NSInvalidException if it is passed nil as the argument. * @param txt_data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::map> dictionary_from_txt_record_data(const std::vector& txt_data); /** * @brief Calls `-[NSNetService getInputStream:outputStream:]`. - * @details Creates a pair of input and output streams for the receiver and returns a Boolean value that indicates whether they were retrieved successfully. - Parameters: - inputStream: Upon return, the input stream for the receiver. Pass 'NULL' if you do not need this stream. - outputStream: Upon return, the output stream for the receiver. Pass 'NULL' if you do not need this stream. - Returns: 'YES' if the streams are created successfully, otherwise 'NO'. After this method is called, no delegate callbacks are called by the receiver. The streams that are created are not open, and are not scheduled in any run loop for any mode. + * @details Retrieves streams from the NSNetService instance. The instance's delegate methods are not called. Returns YES if the streams requested are created successfully. Returns NO if or any reason the stream could not be created. If only one stream is desired, pass NULL for the address of the other stream. The streams that are created are not open, and are not scheduled in any run loop for any mode. * @param input_stream Argument converted to the Objective-C parameter of the same role. * @param output_stream Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -85,102 +84,101 @@ namespace cocoon bool get_input_stream(InputStream& input_stream, OutputStream& output_stream) const; /** * @brief Calls `-[NSNetService publish]`. - * @details Attempts to advertise the receiver's on the network. This method returns immediately, with success or failure indicated by the callbacks to the delegate. This is equivalent to calling '-publishWithOptions:' with the default options ('0'). + * @details Advertises a given service on the network. This method returns immediately. Success or failure is indicated by callbacks to the NSNetService instance's delegate. If the name of the service is the default name (\@""), then the service will be renamed automatically. If the name of the service has been specified, then the service will not be renamed automatically. If more control over renaming is required, then -[NSNetService publishWithOptions:] is available. */ void publish() const; /** * @brief Calls `-[NSNetService publishWithOptions:]`. - * @details Attempts to advertise the receiver on the network, with the given options. - Parameters: - options: Options for the receiver. The supported options are described in 'NSNetServiceOptions'. This method returns immediately, with success or failure indicated by the callbacks to the delegate. + * @details Advertises a given service on the network. This method returns immediately. Success or failure is indicated by callbacks to the NSNetService instance's delegate. See the notes above for NSNetServiceNoAutoRename for information about controlling the auto-renaming behavior using this method. * @param options Argument converted to the Objective-C parameter of the same role. */ void publish_with_options(NetServiceOptions options) const; /** * @brief Calls `-[NSNetService removeFromRunLoop:forMode:]`. - * @details Removes the service from the given run loop for a given mode. - Parameters: - aRunLoop: The run loop from which to remove the receiver. - mode: The run loop mode from which to remove the receiver. You can use this method in conjunction with '-scheduleInRunLoop:forMode:' to transfer the service to a different run loop. Although it is possible to remove an 'NSNetService' object completely from any run loop and then attempt actions on it, it is an error to do so. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void remove_from_run_loop(const RunLoop& a_run_loop, const std::string& mode) const; /** * @brief Calls `-[NSNetService resolveWithTimeout:]`. - * @details Starts a resolve process of a finite duration for the service. - Parameters: - timeout: The maximum number of seconds to attempt a resolve. A value of '0.0' indicates no timeout and a resolve process of indefinite duration. During the resolve period, the service sends '-netServiceDidResolveAddress:' to the delegate for each address it discovers that matches the service parameters. Once the timeout is hit, the service sends '-netServiceDidStop:' to the delegate. If no addresses resolve during the timeout period, the service sends '-netService:didNotResolve:' to the delegate. + * @details Starts a resolve for the NSNetService instance of the specified duration. If the delegate's -netServiceDidResolveAddress: method is called before the timeout expires, the resolve is successful. If the timeout is reached, the delegate's -netService:didNotResolve: method will be called. The value of the NSNetServicesErrorCode key in the error dictionary will be NSNetServicesTimeoutError. * @param timeout Argument converted to the Objective-C parameter of the same role. */ void resolve_with_timeout(double timeout) const; /** * @brief Calls `-[NSNetService scheduleInRunLoop:forMode:]`. - * @details Adds the service to the specified run loop. - Parameters: - aRunLoop: The run loop to which to add the receiver. - mode: The run loop mode to which to add the receiver. You can use this method in conjunction with '-removeFromRunLoop:forMode:' to transfer a service to a different run loop. You should not attempt to run a service on multiple run loops. + * @details NSNetService instances may be scheduled on NSRunLoops to operate in different modes, or in other threads. It is generally not necessary to schedule NSNetServices in other threads. NSNetServices are scheduled in the current thread's NSRunLoop in the NSDefaultRunLoopMode when they are created. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void schedule_in_run_loop(const RunLoop& a_run_loop, const std::string& mode) const; /** * @brief Calls `-[NSNetService setTXTRecordData:]`. - * @details Sets the TXT record for the receiver, and returns a Boolean value that indicates whether the operation was successful. - Parameters: - recordData: The TXT record for the receiver. Pass 'nil' to remove the TXT record from the instance. - Returns: 'YES' if 'recordData' is successfully set as the TXT record, otherwise 'NO'. + * @details Sets the TXT record of the NSNetService instance that has been or will be published. Pass nil to remove the TXT record from the instance. * @param record_data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool set_txt_record_data(const std::vector& record_data) const; /** * @brief Calls `-[NSNetService startMonitoring]`. - * @details Starts the monitoring of TXT-record updates for the receiver. The delegate must implement '-netService:didUpdateTXTRecordData:', which is called when the TXT record for the receiver is updated. + * @details Starts monitoring the NSNetService instance for events. In Mac OS X 10.4 Tiger, monitored NSNetService instances inform their delegates of changes to the instance's TXT record by calling the delegate's -netService:didUpdateTXTRecordData: method. */ void start_monitoring() const; /** * @brief Calls `-[NSNetService stop]`. - * @details Halts a currently running attempt to publish or resolve a service. The delegate will receive '-netServiceDidStop:' after the service stops. It is safe to remove all strong references to the service immediately after calling this method. + * @details Halts a service which is either publishing or resolving. */ void stop() const; /** * @brief Calls `-[NSNetService stopMonitoring]`. - * @details Stops the monitoring of TXT-record updates for the receiver. + * @details Stops monitoring the NSNetService instance for events. */ void stop_monitoring() const; /** * @brief Returns the `addresses` property of `NSNetService`. - * @details A read-only array containing 'NSData' objects, each of which contains a socket address for the service. Each 'NSData' object in the returned array contains an appropriate 'sockaddr' structure that you can use to connect to the socket. The exact type of this structure depends on the service to which you are connecting. If no addresses were resolved for the service, the returned array contains zero elements. It is possible for a single service to resolve to more than one address or not resolve to any addresses. A service might resolve to multiple addresses if the computer publishing the service is currently multihoming. + * @details The addresses of the service. This is an NSArray of NSData instances, each of which contains a single struct sockaddr suitable for use with connect(2). In the event that no addresses are resolved for the service or the service has not yet been resolved, an empty NSArray is returned. * @return The converted Objective-C result. */ std::vector> addresses() const; /** * @brief Returns the `domain` property of `NSNetService`. - * @details A string containing the domain for this service. This can be an explicit domain name or it can contain the generic local domain name, '\@"local."' (note the trailing period, which indicates an absolute name). + * @details Returns the domain of the discovered or published service. * @return The converted Objective-C result. */ std::string domain() const; /** * @brief Returns the `hostName` property of `NSNetService`. - * @details A string containing the DNS hostname for this service. This value is 'nil' until the service has been resolved (when 'addresses' is non-'nil'). + * @details Returns the DNS host name of the computer hosting the discovered or published service. If a successful resolve has not yet occurred, this method will return nil. * @return The converted Objective-C result. */ std::string host_name() const; /** * @brief Returns the `includesPeerToPeer` property of `NSNetService`. - * @details Specifies whether to also publish, resolve, or monitor this service over peer-to-peer Bluetooth and Wi-Fi, if available. This property must be set before calling '-publish', '-publishWithOptions:', '-resolveWithTimeout:', or '-startMonitoring' in order to take effect. Initially set to 'NO'. + * @details Initially set to NO. Set to YES to also publish, resolve, or monitor this service over peer to peer Wi-Fi (if available). Must be set before operation starts. * @return The converted Objective-C result. */ bool includes_peer_to_peer() const; /** * @brief Sets the `includesPeerToPeer` property of `NSNetService`. - * @details Specifies whether to also publish, resolve, or monitor this service over peer-to-peer Bluetooth and Wi-Fi, if available. This property must be set before calling '-publish', '-publishWithOptions:', '-resolveWithTimeout:', or '-startMonitoring' in order to take effect. Initially set to 'NO'. + * @details Initially set to NO. Set to YES to also publish, resolve, or monitor this service over peer to peer Wi-Fi (if available). Must be set before operation starts. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_peer_to_peer(bool value) const; /** * @brief Returns the `name` property of `NSNetService`. - * @details A string containing the name of this service. This value is set when the object is first initialized, whether by your code or by a browser object. + * @details Returns the name of the discovered or published service. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Returns the `port` property of `NSNetService`. - * @details The port on which the service is listening for connections. If the object was initialized by calling '-initWithDomain:type:name:port:', then the value was set when the object was first initialized. If the object was initialized by calling '-initWithDomain:type:name:', the value of this property is not valid ('-1') until after the service has successfully been resolved (when 'addresses' is non-'nil'). + * @details The port of a resolved service. This returns -1 if the service has not been resolved. * @return The converted Objective-C result. */ std::int64_t port() const; /** * @brief Returns the `type` property of `NSNetService`. - * @details The type of the published service. This value is set when the object is first initialized, whether by your code or by a browser object. + * @details Returns the type of the discovered or published service. * @return The converted Objective-C result. */ std::string type() const; diff --git a/include/generated/net_service_browser.h b/include/generated/net_service_browser.h index 77bf747f..1258f391 100644 --- a/include/generated/net_service_browser.h +++ b/include/generated/net_service_browser.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSNetServiceBrowser` (Foundation). - * @details A network service browser that finds published services on a network using multicast DNS. Services can range from standard services, such as HTTP and FTP, to custom services defined by other applications. You can use a network service browser in your code to obtain the list of accessible domains and then to obtain an ''NetService'' object for each discovered service. Each network service browser performs one search at a time, so if you want to perform multiple simultaneous searches, use multiple network service browsers. A network service browser performs all searches asynchronously using the current run loop to execute the search in the background. Results from a search are returned through the associated delegate object, which your client application must provide. Searching proceeds in the background until the object receives a ''stop()'' message. To use an 'NSNetServiceBrowser' object to search for services, allocate it, initialize it, and assign a delegate. (If you wish, you can also use the ''schedule(in:forMode:)'' and ''remove(from:forMode:)'' methods to execute searches on a run loop other than the current one.) Once your object is ready, you begin by gathering the list of accessible domains using either the ''searchForRegistrationDomains()'' or ''searchForBrowsableDomains()'' methods. From the list of returned domains, you can pick one and use the ''searchForServices(ofType:inDomain:)'' method to search for services in that domain. The 'NSNetServiceBrowser' class provides two ways to search for domains. In most cases, your client should use the ''searchForRegistrationDomains()'' method to search only for local domains to which the host machine has registration authority. This is the preferred method for accessing domains as it guarantees that the host machine can connect to services in the returned domains. Access to domains outside this list may be more limited. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -52,49 +51,48 @@ namespace cocoon explicit NetServiceBrowser(Adopt adopt); /** * @brief Calls `-[NSNetServiceBrowser removeFromRunLoop:forMode:]`. - * @details Removes the receiver from the specified run loop. - Parameters: - aRunLoop: Run loop from which to remove the receiver. - mode: Run loop mode in which to perform this operation. You can use this method in conjunction with '-scheduleInRunLoop:forMode:' to transfer the receiver to a run loop other than the default one. Although it is possible to remove an 'NSNetService' object completely from any run loop and then attempt actions on it, you must not do it. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void remove_from_run_loop(const RunLoop& a_run_loop, const std::string& mode) const; /** * @brief Calls `-[NSNetServiceBrowser scheduleInRunLoop:forMode:]`. - * @details Adds the receiver to the specified run loop. - Parameters: - aRunLoop: Run loop in which to schedule the receiver. - mode: Run loop mode in which to perform this operation. You can use this method in conjunction with '-removeFromRunLoop:forMode:' to transfer the receiver to a run loop other than the default one. You should not attempt to run the receiver on multiple run loops. + * @details NSNetServiceBrowser instances may be scheduled on NSRunLoops to operate in different modes, or in other threads. It is generally not necessary to schedule NSNetServiceBrowsers in other threads. NSNetServiceBrowsers are scheduled in the current thread's NSRunLoop in the NSDefaultRunLoopMode when they are created. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void schedule_in_run_loop(const RunLoop& a_run_loop, const std::string& mode) const; /** * @brief Calls `-[NSNetServiceBrowser searchForBrowsableDomains]`. - * @details Initiates a search for domains visible to the host. This method returns immediately. The delegate receives a '-netServiceBrowser:didFindDomain:moreComing:' message for each domain discovered. + * @details Starts a search for domains that are browsable via Bonjour and the computer's network configuration. Discovered domains are reported to the delegate's -netServiceBrowser:didFindDomain:moreComing: method. There may be more than one browsable domain. */ void search_for_browsable_domains() const; /** * @brief Calls `-[NSNetServiceBrowser searchForRegistrationDomains]`. - * @details Initiates a search for domains in which the host may register services. This method returns immediately, sending a '-netServiceBrowserWillSearch:' message to the delegate if the network was ready to initiate the search. The delegate receives a subsequent '-netServiceBrowser:didFindDomain:moreComing:' message for each domain discovered. Most network service browser clients do not have to use this method -- it is sufficient to publish a service with the empty string, which registers it in any available registration domains automatically. + * @details Starts a search for domains in which the network configuration allows registration (i.e. publishing). Most NSNetServiceBrowser clients do not need to use this API, as it is sufficient to publish an NSNetService instance with the empty string (see -[NSNetService initWithDomain:type:name:port:]). Discovered domains are reported to the delegate's -netServiceBrowser:didFindDomain:moreComing: method. There may be more than one registration domain. */ void search_for_registration_domains() const; /** * @brief Calls `-[NSNetServiceBrowser searchForServicesOfType:inDomain:]`. - * @details Starts a search for services of a particular type within a specific domain. - Parameters: - type: Type of the service to search for. Must contain both the service type and transport layer information (e.g. 'http.tcp.'). - domainString: Domain name in which to perform the search. Pass the empty string ('\@""') to search default registration domains. This method returns immediately, sending a '-netServiceBrowserWillSearch:' message to the delegate if the network was ready to initiate the search. The delegate receives subsequent '-netServiceBrowser:didFindService:moreComing:' messages for each service discovered. + * @details Starts a search for services of the specified type in the domain indicated by domainString. For each service discovered, a -netServiceBrowser:foundService:moreComing: message is sent to the NSNetServiceBrowser instance's delegate. * @param type Argument converted to the Objective-C parameter of the same role. * @param domain_string Argument converted to the Objective-C parameter of the same role. */ void search_for_services_of_type(const std::string& type, const std::string& domain_string) const; /** * @brief Calls `-[NSNetServiceBrowser stop]`. - * @details Halts a currently running search or resolution. This method sends a '-netServiceBrowserDidStopSearch:' message to the delegate and causes the browser to discard any pending search results. + * @details Stops the currently running search. */ void stop() const; /** * @brief Returns the `includesPeerToPeer` property of `NSNetServiceBrowser`. - * @details Whether to browse over peer-to-peer Bluetooth and Wi-Fi, if available. This property must be set before initiating a search to have an effect. Initially set to 'NO'. + * @details Initially set to NO. Set to YES to also browse over peer to peer Wi-Fi (if available). Must be set before starting to search. * @return The converted Objective-C result. */ bool includes_peer_to_peer() const; /** * @brief Sets the `includesPeerToPeer` property of `NSNetServiceBrowser`. - * @details Whether to browse over peer-to-peer Bluetooth and Wi-Fi, if available. This property must be set before initiating a search to have an effect. Initially set to 'NO'. + * @details Initially set to NO. Set to YES to also browse over peer to peer Wi-Fi (if available). Must be set before starting to search. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_peer_to_peer(bool value) const; diff --git a/include/generated/notification.h b/include/generated/notification.h index 22f7a2b9..5cb79006 100644 --- a/include/generated/notification.h +++ b/include/generated/notification.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSNotification` (Foundation). - * @details A container for information broadcast through a notification center to all registered observers. In Swift, this object bridges to ''Notification''; use ''NSNotification'' when you need reference semantics or other Foundation-specific behavior. A notification contains a name, an object, and an optional dictionary, and is broadcast to by instances of ''NotificationCenter'' or ''DistributedNotificationCenter''. The name is a tag identifying the notification. The object is any object that the poster of the notification wants to send to observers of that notification (typically, the object posting the notification). The dictionary stores other related objects, if any. ''NSNotification'' objects are immutable. You don't usually create your own notifications directly, but instead call the ''NotificationCenter'' methods ''NotificationCenter/post(name:object:)'' and ''NotificationCenter/post(name:object:userInfo:)''. > Important: > The Swift overlay to the Foundation framework provides the ''Notification'' structure, which bridges to the ''NSNotification'' class. For more information about value types, see \. \#\#\# Object Comparison The objects of a notification are compared using pointer equality for local notifications. Distributed notifications use strings as their objects, and those strings are compared using \, because pointer equality doesn't make sense across process boundaries. \#\#\# Creating Subclasses You can subclass ''NSNotification'' to contain information in addition to the notification name, object, and dictionary. This extra data must be agreed upon between notifiers and observers. ''NotificationCenter'' is a class cluster with no instance variables. As such, you must subclass ''NSNotification'' and override the primitive methods ''name'', ''object'', and ''userInfo''. You can choose any designated initializer you like, but be sure that your initializer does not call ''init'' on 'super' (''NSNotification'' is not meant to be instantiated directly, and its 'init' method raises an exception). + * @details Notifications * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -36,19 +36,16 @@ namespace cocoon explicit Notification(Adopt adopt); /** * @brief Returns the `name` property of `NSNotification`. - * @details The name of the notification. Typically you use this property to find out what kind of notification you are dealing with when you receive a notification. Notification names can be any string. To avoid name collisions, you might want to use a prefix that's specific to your application. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Returns the `object` property of `NSNotification`. - * @details The object associated with the notification. This is often the object that posted this notification. It may be 'nil'. Typically you use this method to find out what object a notification applies to when you receive a notification. * @return The converted Objective-C result. */ Object object() const; /** * @brief Returns the `userInfo` property of `NSNotification`. - * @details The user information dictionary associated with the notification. This may be 'nil'. The user information dictionary stores any additional objects that objects receiving the notification might use. * @return The converted Objective-C result. */ std::vector> user_info() const; diff --git a/include/generated/notification_center.h b/include/generated/notification_center.h index e428a2e1..6eca1a2f 100644 --- a/include/generated/notification_center.h +++ b/include/generated/notification_center.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSNotificationCenter` (Foundation). - * @details A notification dispatch mechanism that enables the broadcast of information to registered observers. Callers register with a notification center to receive one or both of the following: ''NSNotification'' objects, when working in Objective-C or with frameworks that only support ''NSNotification''. Objects register with a notification center to receive notifications (''NSNotification'' objects) using the ''addObserver(:selector:name:object:)'' or ''addObserver(forName:object:queue:using:)'' methods, specifying a notification name and optionally a source object. When a caller adds itself as an observer, it specifies which notifications it should receive. ''MainActorMessage'' and ''AsyncMessage'' instances for use with Swift code, providing strong typing, appropriate actor isolation, and a more idiomatic Swift experience. Callers register with the notification center using the various flavors of the 'addObserver(of:for:using:)' method, specifying either a message type or a convenience ''MessageIdentifier'' to identify the notification messages to receive. See \ for more information about this API. Callers may add observers for many different notifications, or even the same notification name or message type as produced by different source objects. Each running app has a ''default'' notification center, and you can create new notification centers to organize communications in particular contexts. A notification center can deliver notifications only within a single program. On macOS, if you want to post a notification to other processes or receive notifications from other processes, use ''DistributedNotificationCenter'' instead. + * @details Notification Center * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -42,7 +42,6 @@ namespace cocoon explicit NotificationCenter(Adopt adopt); /** * @brief Calls `-[NSNotificationCenter addObserver:selector:name:object:]`. - * @details Adds an entry to the notification center to call the provided selector with the notification. - Parameters: - observer: Object registering as an observer. - aSelector: Selector that specifies the message the receiver sends the observer when posting the notification. The method must have one and only one argument (an instance of 'NSNotification'). - aName: The name of the notification for which to register the observer; that is, only notifications with this name are used to add the block to the operation queue. Pass 'nil' to receive notifications with any name. - anObject: The object whose notifications the observer wants to receive; that is, only notifications sent by this sender are delivered to the observer. Pass 'nil' to receive notifications from any sender. * @param observer Argument converted to the Objective-C parameter of the same role. * @param a_selector Argument converted to the Objective-C parameter of the same role. * @param a_name Argument converted to the Objective-C parameter of the same role. @@ -51,7 +50,6 @@ namespace cocoon void add_observer(const Object& observer, const std::string& a_selector, const std::string& a_name, const Object& an_object) const; /** * @brief Calls `-[NSNotificationCenter addObserverForName:object:queue:usingBlock:]`. - * @details Adds an entry to the notification center to receive notifications that passed to the provided block. - Parameters: - name: The name of the notification for which to register the observer. Pass 'nil' to receive notifications with any name. - obj: The object whose notifications the observer wants to receive. Pass 'nil' to receive notifications from any sender. - queue: The operation queue to which the block is added. Pass 'nil' to run the block synchronously on the posting thread. - block: The block to be executed when the notification is received. - Returns: An opaque object to act as the observer, which you use to deregister the observer with ''removeObserver:''. * @param name Argument converted to the Objective-C parameter of the same role. * @param obj Argument converted to the Objective-C parameter of the same role. * @param queue Argument converted to the Objective-C parameter of the same role. @@ -61,20 +59,17 @@ namespace cocoon Object add_observer_for_name(const std::string& name, const Object& obj, const OperationQueue& queue, std::function block) const; /** * @brief Calls `-[NSNotificationCenter postNotification:]`. - * @details Posts a given notification to the notification center. - Parameter notification: The notification to post. * @param notification Argument converted to the Objective-C parameter of the same role. */ void post_notification(const Notification& notification) const; /** * @brief Calls `-[NSNotificationCenter postNotificationName:object:]`. - * @details Creates a notification with a given name and sender and posts it to the notification center. - Parameters: - aName: The name of the notification. - anObject: The object posting the notification. * @param a_name Argument converted to the Objective-C parameter of the same role. * @param an_object Argument converted to the Objective-C parameter of the same role. */ void post_notification_name(const std::string& a_name, const Object& an_object) const; /** * @brief Calls `-[NSNotificationCenter postNotificationName:object:userInfo:]`. - * @details Creates a notification with a given name, sender, and information and posts it to the notification center. - Parameters: - aName: The name of the notification. - anObject: The object posting the notification. - aUserInfo: Optional information about the notification. * @param a_name Argument converted to the Objective-C parameter of the same role. * @param an_object Argument converted to the Objective-C parameter of the same role. * @param a_user_info Argument converted to the Objective-C parameter of the same role. @@ -82,13 +77,11 @@ namespace cocoon void post_notification_name(const std::string& a_name, const Object& an_object, const std::vector>& a_user_info) const; /** * @brief Calls `-[NSNotificationCenter removeObserver:]`. - * @details Removes all entries specifying an observer from the notification center's dispatch table. - Parameter observer: The notification observer to remove. * @param observer Argument converted to the Objective-C parameter of the same role. */ void remove_observer(const Object& observer) const; /** * @brief Calls `-[NSNotificationCenter removeObserver:name:object:]`. - * @details Removes matching entries from the notification center's dispatch table. - Parameters: - observer: The notification observer to remove. - aName: The name of the notification to remove from the dispatch table. Pass 'nil' to remove all entries for the observer. - anObject: The sender to remove from the dispatch table. Pass 'nil' to remove the observer regardless of the sender. * @param observer Argument converted to the Objective-C parameter of the same role. * @param a_name Argument converted to the Objective-C parameter of the same role. * @param an_object Argument converted to the Objective-C parameter of the same role. @@ -96,7 +89,6 @@ namespace cocoon void remove_observer(const Object& observer, const std::string& a_name, const Object& an_object) const; /** * @brief Returns the `defaultCenter` property of `NSNotificationCenter`. - * @details The app's default notification center. * @return The converted Objective-C result. */ static NotificationCenter default_center(); diff --git a/include/generated/notification_queue.h b/include/generated/notification_queue.h index 57b81cf2..e005d12d 100644 --- a/include/generated/notification_queue.h +++ b/include/generated/notification_queue.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSNotificationQueue` (Foundation). - * @details A notification center buffer. Whereas a notification center distributes notifications when posted, notifications placed into the queue can be delayed until the end of the current pass through the run loop or until the run loop is idle. Duplicate notifications can be coalesced so that only one notification is sent although multiple notifications are posted. A notification queue maintains notifications in first in, first out (FIFO) order. When a notification moves to the front of the queue, the queue posts it to the notification center, which in turn dispatches the notification to all objects registered as observers. Every thread has a default notification queue, which is associated with the default notification center for the process. You can create your own notification queues and have multiple queues per center and thread. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -46,21 +45,18 @@ namespace cocoon explicit NotificationQueue(Adopt adopt); /** * @brief Calls `-[NSNotificationQueue dequeueNotificationsMatching:coalesceMask:]`. - * @details Removes all notifications from the queue that match a provided notification using provided matching criteria. * @param notification Argument converted to the Objective-C parameter of the same role. * @param coalesce_mask Argument converted to the Objective-C parameter of the same role. */ void dequeue_notifications_matching(const Notification& notification, std::uint64_t coalesce_mask) const; /** * @brief Calls `-[NSNotificationQueue enqueueNotification:postingStyle:]`. - * @details Adds a notification to the notification queue with a specified posting style. * @param notification Argument converted to the Objective-C parameter of the same role. * @param posting_style Argument converted to the Objective-C parameter of the same role. */ void enqueue_notification(const Notification& notification, PostingStyle posting_style) const; /** * @brief Calls `-[NSNotificationQueue enqueueNotification:postingStyle:coalesceMask:forModes:]`. - * @details Adds a notification to the notification queue with a specified posting style, criteria for coalescing, and run loop mode. The notification queue will only post the notification to its notification center if the run loop is in one of the modes provided in the array. The modes parameter may be nil, in which case it defaults to NSDefaultRunLoopMode. * @param notification Argument converted to the Objective-C parameter of the same role. * @param posting_style Argument converted to the Objective-C parameter of the same role. * @param coalesce_mask Argument converted to the Objective-C parameter of the same role. @@ -69,7 +65,6 @@ namespace cocoon void enqueue_notification(const Notification& notification, PostingStyle posting_style, NotificationCoalescing coalesce_mask, const std::vector& modes) const; /** * @brief Returns the `defaultQueue` property of `NSNotificationQueue`. - * @details Returns the default notification queue for the current thread. This notification queue uses the default notification center. * @return The converted Objective-C result. */ static NotificationQueue default_queue(); diff --git a/include/generated/null.h b/include/generated/null.h index 155012b3..1f74075b 100644 --- a/include/generated/null.h +++ b/include/generated/null.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSNull` (Foundation). - * @details A singleton object used to represent null values in collection objects that don't allow 'nil' values. ''NSNull'' is "toll-free bridged" with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example diff --git a/include/generated/number.h b/include/generated/number.h index dfba27a5..5001a2b2 100644 --- a/include/generated/number.h +++ b/include/generated/number.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSNumber` (Foundation). - * @details An object wrapper for primitive scalar numeric values. 'NSNumber' is a subclass of 'NSValue' that offers a value as any C scalar (numeric) type. It defines a set of methods specifically for setting and accessing the value as a signed or unsigned 'char', 'short int', 'int', 'long int', 'long long int', 'float', or 'double' or as a 'BOOL'. (Note that number objects do not necessarily preserve the type they are created with.) It also defines a ''compare(:)'' method to determine the ordering of two 'NSNumber' objects. 'NSNumber' is "toll-free bridged" with its Core Foundation counterparts: \ for integer and floating point values, and \ for Boolean values. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. \#\#\# Value Conversions 'NSNumber' provides readonly properties that return the object's stored value converted to a particular Boolean, integer, unsigned integer, or floating point C scalar type. Because numeric types have different storage capabilities, attempting to initialize with a value of one type and access the value of another type may produce an erroneous result—for example, initializing with a 'double' value exceeding 'FLT_MAX' and accessing its ''floatValue'', or initializing with an negative integer value and accessing its ''uintValue''. In some cases, attempting to initialize with a value of a type and access the value of another type may result in loss of precision—for example, initializing with a 'double' value with many significant digits and accessing its ''floatValue'', or initializing with a large integer value and accessing its ''int8Value''. An 'NSNumber' object initialized with a value of a particular type accessing the converted value of a different kind of type, such as 'unsigned int' and 'float', will convert its stored value to that converted type in the following ways: | 'Value' | ''boolValue'' | ''intValue-95zzp'' | ''uintValue'' | ''floatValue'' | |---|---|---|---|---| | \ | \ | '0' | '0' | '0.0' | | \ | \ | '1' | '1' | '1.0' | | 'Value' | ''boolValue'' | ''intValue-95zzp'' | ''uintValue'' | ''floatValue'' | |---|---|---|---|---| | '0' | \ | '0' | '0' | '0.0' | | '1' | \ | '1' | '1' | '1.0' | | '-1' | \ | '-1' | invalid, erroneous result | '-1.0' | | 'Value' | ''boolValue'' | ''intValue-95zzp'' | ''uintValue'' | ''floatValue'' | |---|---|---|---|---| | '0' | \ | '0' | '0' | '0.0' | | '1' | \ | '1' | '1' | '1.0' | | 'Value' | ''boolValue'' | ''intValue-95zzp'' | ''uintValue'' | ''floatValue'' | |---|---|---|---|---| | '0.0' | \ | '0' | '0' | '0.0' | | '1.0' | \ | '1' | '1' | '1.0' | | '-1.0' | \ | '-1' | invalid, erroneous result | '-1.0' | \#\#\# Subclassing Notes As with any class cluster, subclasses of 'NSNumber' must override the primitive methods of its superclass, 'NSValue'. In addition, there are two requirements around the data type your subclass represents: 1. Your implementation of ''NSValue/objCType'' must return one of "'c'", "'C'", "'s'", "'S'", "'i'", "'I'", "'l'", "'L'", "'q'", "'Q'", "'f'", and "'d'". This is required for the other methods of ''NSNumber'' to behave correctly. 2. Your subclass must override the accessor method that corresponds to the declared type—for example, if your implementation of ''NSValue/objCType'' returns "'i'", you must override ''int32Value''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Value. * @@ -63,34 +62,29 @@ namespace cocoon explicit Number(Adopt adopt); /** * @brief Calls `-[NSNumber compare:]`. - * @details Returns an 'NSComparisonResult' value that indicates whether the number object's value is greater than, equal to, or less than a given number. - Parameter otherNumber: The number to compare to the number object's value. This value must not be 'nil'. - Returns: 'NSOrderedAscending' if the value of 'otherNumber' is greater than the number object's, 'NSOrderedSame' if they're equal, and 'NSOrderedDescending' if the value of 'otherNumber' is less than the number object's. The ''NSNumber/compare:'' method follows the standard C rules for type conversion. For example, if you compare an 'NSNumber' object that has an integer value with an 'NSNumber' object that has a floating point value, the integer value is converted to a floating-point value for comparison. * @param other_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ComparisonResult compare(const Number& other_number) const; /** * @brief Calls `-[NSNumber descriptionWithLocale:]`. - * @details Returns a string that represents the contents of the number object for a given locale. - Parameter locale: An object containing locale information with which to format the description. Use 'nil' if you don't want the description formatted. - Returns: A string that represents the contents of the number object formatted using the locale information in 'locale'. * @param locale Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string description_with_locale(const Object& locale) const; /** * @brief Calls `-[NSNumber isEqualToNumber:]`. - * @details Returns a Boolean value that indicates whether the number object's value and a given number are equal. - Parameter number: The number to compare to the number object's value. - Returns: 'YES' if the number object's value and 'number' are equal; otherwise, 'NO'. Two 'NSNumber' objects are considered equal if they have the same id values or if they have equivalent values (as determined by the ''NSNumber/compare:'' method). This method is more efficient than ''NSNumber/compare:'' if you know the two objects are numbers. * @param number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equal_to_number(const Number& number) const; /** * @brief Returns the `boolValue` property of `NSNumber`. - * @details The number object's value expressed as a Boolean value. A '0' value always means 'NO', and any nonzero value is interpreted as 'YES'. * @return The converted Objective-C result. */ bool bool_value() const; /** * @brief Returns the `charValue` property of `NSNumber`. - * @details The number object's value expressed as a 'char'. * @return The converted Objective-C result. */ std::int8_t char_value() const; @@ -101,85 +95,71 @@ namespace cocoon Decimal decimal_value() const; /** * @brief Returns the `doubleValue` property of `NSNumber`. - * @details The number object's value expressed as a 'double'. * @return The converted Objective-C result. */ double double_value() const; /** * @brief Returns the `floatValue` property of `NSNumber`. - * @details The number object's value expressed as a 'float'. * @return The converted Objective-C result. */ float float_value() const; /** * @brief Returns the `intValue` property of `NSNumber`. - * @details The number object's value expressed as an 'int'. * @return The converted Objective-C result. */ int int_value() const; /** * @brief Returns the `integerValue` property of `NSNumber`. - * @details The number object's value expressed as an 'NSInteger'. * @return The converted Objective-C result. */ std::int64_t integer_value() const; /** * @brief Returns the `longLongValue` property of `NSNumber`. - * @details The number object's value expressed as a 'long long'. * @return The converted Objective-C result. */ std::int64_t long_long_value() const; /** * @brief Returns the `longValue` property of `NSNumber`. - * @details The number object's value expressed as a 'long'. * @return The converted Objective-C result. */ std::int64_t long_value() const; /** * @brief Returns the `shortValue` property of `NSNumber`. - * @details The number object's value expressed as a 'short'. * @return The converted Objective-C result. */ std::int16_t short_value() const; /** * @brief Returns the `stringValue` property of `NSNumber`. - * @details The number object's value expressed as a human-readable string. The string is created by invoking ''NSNumber/descriptionWithLocale:'' where locale is 'nil'. * @return The converted Objective-C result. */ std::string string_value() const; /** * @brief Returns the `unsignedCharValue` property of `NSNumber`. - * @details The number object's value expressed as an 'unsigned char'. * @return The converted Objective-C result. */ std::uint8_t unsigned_char_value() const; /** * @brief Returns the `unsignedIntValue` property of `NSNumber`. - * @details The number object's value expressed as an 'unsigned int'. * @return The converted Objective-C result. */ unsigned int unsigned_int_value() const; /** * @brief Returns the `unsignedIntegerValue` property of `NSNumber`. - * @details The number object's value expressed as an 'NSUInteger'. * @return The converted Objective-C result. */ std::uint64_t unsigned_integer_value() const; /** * @brief Returns the `unsignedLongLongValue` property of `NSNumber`. - * @details The number object's value expressed as an 'unsigned long long'. * @return The converted Objective-C result. */ std::uint64_t unsigned_long_long_value() const; /** * @brief Returns the `unsignedLongValue` property of `NSNumber`. - * @details The number object's value expressed as an 'unsigned long'. * @return The converted Objective-C result. */ std::uint64_t unsigned_long_value() const; /** * @brief Returns the `unsignedShortValue` property of `NSNumber`. - * @details The number object's value expressed as an 'unsigned short'. * @return The converted Objective-C result. */ std::uint16_t unsigned_short_value() const; diff --git a/include/generated/number_formatter.h b/include/generated/number_formatter.h index ed0e4130..d54d3441 100644 --- a/include/generated/number_formatter.h +++ b/include/generated/number_formatter.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSNumberFormatter` (Foundation). - * @details A formatter that converts between numeric values and their textual representations. Instances of ''NumberFormatter'' format the textual representation of cells that contain ''NSNumber'' objects and convert textual representations of numeric values into ''NSNumber'' objects. The representation encompasses integers, floats, and doubles; floats and doubles can be formatted to a specified decimal position. ''NumberFormatter'' objects can also impose ranges on the numeric values cells can accept. > Tip: > In Swift, you can use ''IntegerFormatStyle'', ''FloatingPointFormatStyle'', or ''Decimal/FormatStyle'' rather than ''NumberFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. \#\#\# Significant Digits and Fraction Digits The ''NumberFormatter'' class provides flexible options for displaying non-zero fractional parts of numbers. If you set the ''usesSignificantDigits'' property to \, you can configure ''NumberFormatter'' to display significant digits using the ''minimumSignificantDigits'' and ''maximumSignificantDigits'' properties. If ''usesSignificantDigits'' is \, these properties are ignored. See Configuring Significant Digits. Otherwise, you can configure the minimum and maximum number of integer and fraction digits, or the numbers before and after the decimal separator, respectively, using the ''minimumIntegerDigits'', ''maximumIntegerDigits'', ''minimumFractionDigits'', and ''maximumFractionDigits'' properties. See Configuring Integer and Fraction Digits. \#\#\# Thread Safety On iOS 7 and later ''NumberFormatter'' is thread-safe. In macOS 10.9 and later ''NumberFormatter'' is thread-safe so long as you are using the modern behavior in a 64-bit app. On earlier versions of the operating system, or when using the legacy formatter behavior or running in 32-bit in macOS, ''NumberFormatter'' is not thread-safe, and you therefore must not mutate a number formatter simultaneously from multiple threads. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -53,13 +52,11 @@ namespace cocoon explicit NumberFormatter(Adopt adopt); /** * @brief Calls `+[NSNumberFormatter defaultFormatterBehavior]`. - * @details Returns an \\c NSNumberFormatterBehavior constant that indicates default formatter behavior for new instances of \\c NSNumberFormatter. * @return The converted Objective-C result. */ static NumberFormatterBehavior default_formatter_behavior(); /** * @brief Calls `+[NSNumberFormatter localizedStringFromNumber:numberStyle:]`. - * @details Returns a localized number string with the specified style. \@param num The number to localize. \@param nstyle The localization style to use. \@return An appropriately formatted \\c NSString. * @param num Argument converted to the Objective-C parameter of the same role. * @param nstyle Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -67,813 +64,678 @@ namespace cocoon static std::string localized_string_from_number(const Number& num, NumberFormatterStyle nstyle); /** * @brief Calls `-[NSNumberFormatter numberFromString:]`. - * @details Returns an \\c NSNumber object created by parsing a given string. If a string contains any characters other than numerical digits or locale-appropriate group or decimal separators, parsing will fail. Any leading or trailing space separator characters in a string are ignored. For example, the strings " 5", "5 ", and "5" all produce the number \\c 5. \@param string An \\c NSString object that is parsed to generate the returned number object. \@return An \\c NSNumber object created by parsing \\c string using the receiver's format, or \\c nil if no single number could be parsed. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Number number_from_string(const std::string& string) const; /** * @brief Calls `+[NSNumberFormatter setDefaultFormatterBehavior:]`. - * @details Sets the default formatter behavior for new instances of \\c NSNumberFormatter. \@param behavior An \\c NSNumberFormatterBehavior constant that indicates the revision of the class providing the default behavior. * @param behavior Argument converted to the Objective-C parameter of the same role. */ static void set_default_formatter_behavior(NumberFormatterBehavior behavior); /** * @brief Calls `-[NSNumberFormatter stringFromNumber:]`. - * @details Returns a string containing the formatted value of the provided number object. \@param number An \\c NSNumber object that is parsed to create the returned string object. \@return A string containing the formatted value of \\c number using the receiver's current settings. * @param number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_number(const Number& number) const; /** * @brief Returns the `allowsFloats` property of `NSNumberFormatter`. - * @details Determines whether the receiver allows as input floating-point values (that is, values that include the period character (\\c .)). By default, floating point values are allowed. * @return The converted Objective-C result. */ bool allows_floats() const; /** * @brief Sets the `allowsFloats` property of `NSNumberFormatter`. - * @details Determines whether the receiver allows as input floating-point values (that is, values that include the period character (\\c .)). By default, floating point values are allowed. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_floats(bool value) const; /** * @brief Returns the `alwaysShowsDecimalSeparator` property of `NSNumberFormatter`. - * @details Determines whether the receiver always shows the decimal separator, even for integer numbers. * @return The converted Objective-C result. */ bool always_shows_decimal_separator() const; /** * @brief Sets the `alwaysShowsDecimalSeparator` property of `NSNumberFormatter`. - * @details Determines whether the receiver always shows the decimal separator, even for integer numbers. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_always_shows_decimal_separator(bool value) const; /** * @brief Returns the `attributedStringForNil` property of `NSNumberFormatter`. - * @details The attributed string the receiver uses to display \\c nil values. By default \\c nil values are displayed as an empty string. This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @return The converted Objective-C result. */ AttributedString attributed_string_for_nil() const; /** * @brief Sets the `attributedStringForNil` property of `NSNumberFormatter`. - * @details The attributed string the receiver uses to display \\c nil values. By default \\c nil values are displayed as an empty string. This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attributed_string_for_nil(const AttributedString& value) const; /** * @brief Returns the `attributedStringForNotANumber` property of `NSNumberFormatter`. - * @details The attributed string the receiver uses to display "not a number" values. By default "not a number" values are displayed as the string "NaN". This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @return The converted Objective-C result. */ AttributedString attributed_string_for_not_a_number() const; /** * @brief Sets the `attributedStringForNotANumber` property of `NSNumberFormatter`. - * @details The attributed string the receiver uses to display "not a number" values. By default "not a number" values are displayed as the string "NaN". This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attributed_string_for_not_a_number(const AttributedString& value) const; /** * @brief Returns the `attributedStringForZero` property of `NSNumberFormatter`. - * @details The attributed string that the receiver uses to display zero values. By default zero values are displayed according to the format specified for positive values. This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @return The converted Objective-C result. */ AttributedString attributed_string_for_zero() const; /** * @brief Sets the `attributedStringForZero` property of `NSNumberFormatter`. - * @details The attributed string that the receiver uses to display zero values. By default zero values are displayed according to the format specified for positive values. This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attributed_string_for_zero(const AttributedString& value) const; /** * @brief Returns the `currencyCode` property of `NSNumberFormatter`. - * @details The receiver's currency code. A currency code is a three-letter code that is, in most cases, composed of a region's two-character Internet region code plus an extra character to denote the currency unit. For example, the currency code for the Australian dollar is "AUD". Currency codes are based on the ISO 4217 standard. * @return The converted Objective-C result. */ std::string currency_code() const; /** * @brief Sets the `currencyCode` property of `NSNumberFormatter`. - * @details The receiver's currency code. A currency code is a three-letter code that is, in most cases, composed of a region's two-character Internet region code plus an extra character to denote the currency unit. For example, the currency code for the Australian dollar is "AUD". Currency codes are based on the ISO 4217 standard. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_currency_code(const std::string& value) const; /** * @brief Returns the `currencyDecimalSeparator` property of `NSNumberFormatter`. - * @details The string used by the receiver as a currency decimal separator. * @return The converted Objective-C result. */ std::string currency_decimal_separator() const; /** * @brief Sets the `currencyDecimalSeparator` property of `NSNumberFormatter`. - * @details The string used by the receiver as a currency decimal separator. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_currency_decimal_separator(const std::string& value) const; /** * @brief Returns the `currencyGroupingSeparator` property of `NSNumberFormatter`. - * @details The currency grouping separator for the receiver. * @return The converted Objective-C result. */ std::string currency_grouping_separator() const; /** * @brief Sets the `currencyGroupingSeparator` property of `NSNumberFormatter`. - * @details The currency grouping separator for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_currency_grouping_separator(const std::string& value) const; /** * @brief Returns the `currencySymbol` property of `NSNumberFormatter`. - * @details The string used by the receiver as a local currency symbol. A region typically has a local currency symbol and an international currency symbol. The local symbol is used within the region, while the international currency symbol is used in international contexts to specify that region's currency unambiguously. The local currency symbol is often represented by a Unicode code point. * @return The converted Objective-C result. */ std::string currency_symbol() const; /** * @brief Sets the `currencySymbol` property of `NSNumberFormatter`. - * @details The string used by the receiver as a local currency symbol. A region typically has a local currency symbol and an international currency symbol. The local symbol is used within the region, while the international currency symbol is used in international contexts to specify that region's currency unambiguously. The local currency symbol is often represented by a Unicode code point. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_currency_symbol(const std::string& value) const; /** * @brief Returns the `decimalSeparator` property of `NSNumberFormatter`. - * @details The character the receiver uses as a decimal separator. * @return The converted Objective-C result. */ std::string decimal_separator() const; /** * @brief Sets the `decimalSeparator` property of `NSNumberFormatter`. - * @details The character the receiver uses as a decimal separator. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_decimal_separator(const std::string& value) const; /** * @brief Returns the `exponentSymbol` property of `NSNumberFormatter`. - * @details The string used to represent an exponent symbol. By default, this property is set to the latin capital letter E. The exponent symbol is the "E" or "e" in the scientific notation of numbers, as in "1.0E+42". * @return The converted Objective-C result. */ std::string exponent_symbol() const; /** * @brief Sets the `exponentSymbol` property of `NSNumberFormatter`. - * @details The string used to represent an exponent symbol. By default, this property is set to the latin capital letter E. The exponent symbol is the "E" or "e" in the scientific notation of numbers, as in "1.0E+42". * @param value Argument converted to the Objective-C parameter of the same role. */ void set_exponent_symbol(const std::string& value) const; /** * @brief Returns the `format` property of `NSNumberFormatter`. - * @details The receiver's format. The format string uses the format patterns from the Unicode Technical Standard \#35. For more information, see the Data Formatting Guide. * @return The converted Objective-C result. */ std::string format() const; /** * @brief Sets the `format` property of `NSNumberFormatter`. - * @details The receiver's format. The format string uses the format patterns from the Unicode Technical Standard \#35. For more information, see the Data Formatting Guide. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_format(const std::string& value) const; /** * @brief Returns the `formatWidth` property of `NSNumberFormatter`. - * @details The format width used by the receiver. The format width is the number of characters of a formatted number within a string that is either left justified or right justified based on the value contained in \\c paddingPosition. * @return The converted Objective-C result. */ std::uint64_t format_width() const; /** * @brief Sets the `formatWidth` property of `NSNumberFormatter`. - * @details The format width used by the receiver. The format width is the number of characters of a formatted number within a string that is either left justified or right justified based on the value contained in \\c paddingPosition. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_format_width(std::uint64_t value) const; /** * @brief Returns the `formatterBehavior` property of `NSNumberFormatter`. - * @details The formatter behavior of the receiver. * @return The converted Objective-C result. */ NumberFormatterBehavior formatter_behavior() const; /** * @brief Sets the `formatterBehavior` property of `NSNumberFormatter`. - * @details The formatter behavior of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_formatter_behavior(NumberFormatterBehavior value) const; /** * @brief Returns the `formattingContext` property of `NSNumberFormatter`. - * @details The capitalization formatting context used when formatting a number. Defaults to \\c NSFormattingContextUnknown. * @return The converted Objective-C result. */ FormattingContext formatting_context() const; /** * @brief Sets the `formattingContext` property of `NSNumberFormatter`. - * @details The capitalization formatting context used when formatting a number. Defaults to \\c NSFormattingContextUnknown. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_formatting_context(FormattingContext value) const; /** * @brief Returns the `generatesDecimalNumbers` property of `NSNumberFormatter`. - * @details Determines whether the receiver creates instances of \\c NSDecimalNumber when it converts strings to number objects. * @return The converted Objective-C result. */ bool generates_decimal_numbers() const; /** * @brief Sets the `generatesDecimalNumbers` property of `NSNumberFormatter`. - * @details Determines whether the receiver creates instances of \\c NSDecimalNumber when it converts strings to number objects. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_generates_decimal_numbers(bool value) const; /** * @brief Returns the `groupingSeparator` property of `NSNumberFormatter`. - * @details The string used by the receiver for a grouping separator. For example, the grouping separator used in the United States is the comma ("10,000") whereas in France it is the space ("10 000"). * @return The converted Objective-C result. */ std::string grouping_separator() const; /** * @brief Sets the `groupingSeparator` property of `NSNumberFormatter`. - * @details The string used by the receiver for a grouping separator. For example, the grouping separator used in the United States is the comma ("10,000") whereas in France it is the space ("10 000"). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_grouping_separator(const std::string& value) const; /** * @brief Returns the `groupingSize` property of `NSNumberFormatter`. - * @details The grouping size of the receiver. * @return The converted Objective-C result. */ std::uint64_t grouping_size() const; /** * @brief Sets the `groupingSize` property of `NSNumberFormatter`. - * @details The grouping size of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_grouping_size(std::uint64_t value) const; /** * @brief Returns the `hasThousandSeparators` property of `NSNumberFormatter`. - * @details Determines whether the receiver uses thousand separators. * @return The converted Objective-C result. */ bool has_thousand_separators() const; /** * @brief Sets the `hasThousandSeparators` property of `NSNumberFormatter`. - * @details Determines whether the receiver uses thousand separators. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_has_thousand_separators(bool value) const; /** * @brief Returns the `internationalCurrencySymbol` property of `NSNumberFormatter`. - * @details The international currency symbol used by the receiver. A region typically has a local currency symbol and an international currency symbol. The local symbol is used within the region, while the international currency symbol is used in international contexts to specify that region's currency unambiguously. The international currency symbol is often represented by a Unicode code point. * @return The converted Objective-C result. */ std::string international_currency_symbol() const; /** * @brief Sets the `internationalCurrencySymbol` property of `NSNumberFormatter`. - * @details The international currency symbol used by the receiver. A region typically has a local currency symbol and an international currency symbol. The local symbol is used within the region, while the international currency symbol is used in international contexts to specify that region's currency unambiguously. The international currency symbol is often represented by a Unicode code point. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_international_currency_symbol(const std::string& value) const; /** * @brief Returns the `lenient` property of `NSNumberFormatter`. - * @details Determines whether the receiver will use heuristics to guess at the number which is intended by a string. If the formatter is set to be lenient, as with any guessing it may get the result number wrong (that is, a number other than that which was intended). * @return The converted Objective-C result. */ bool is_lenient() const; /** * @brief Sets the `lenient` property of `NSNumberFormatter`. - * @details Determines whether the receiver will use heuristics to guess at the number which is intended by a string. If the formatter is set to be lenient, as with any guessing it may get the result number wrong (that is, a number other than that which was intended). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_lenient(bool value) const; /** * @brief Returns the `locale` property of `NSNumberFormatter`. - * @details The locale of the receiver. The locale determines the default values for many formatter attributes, such as ISO region and language codes, currency code, calendar, system of measurement, and decimal separator. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSNumberFormatter`. - * @details The locale of the receiver. The locale determines the default values for many formatter attributes, such as ISO region and language codes, currency code, calendar, system of measurement, and decimal separator. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; /** * @brief Returns the `localizesFormat` property of `NSNumberFormatter`. - * @details Determines whether the dollar sign character (\\c $), decimal separator character (\\c .), and thousand separator character (\\c ,) are converted to appropriately localized characters as specified by the user's localization preference. While the currency-symbol part of this feature may be useful in certain types of applications, it's probably more likely that you would tie a particular application to a particular currency (that is, that you would "hard-code" the currency symbol and separators instead of having them dynamically change based on the user's configuration). The reason for this, of course, is that \\c NSNumberFormatter doesn't perform currency conversions, it just formats numeric data. You wouldn't want one user interpreting the value "56324" as US currency and another user who's accessing the same data interpreting it as Japanese currency, simply based on each user's localization preferences. * @return The converted Objective-C result. */ bool localizes_format() const; /** * @brief Sets the `localizesFormat` property of `NSNumberFormatter`. - * @details Determines whether the dollar sign character (\\c $), decimal separator character (\\c .), and thousand separator character (\\c ,) are converted to appropriately localized characters as specified by the user's localization preference. While the currency-symbol part of this feature may be useful in certain types of applications, it's probably more likely that you would tie a particular application to a particular currency (that is, that you would "hard-code" the currency symbol and separators instead of having them dynamically change based on the user's configuration). The reason for this, of course, is that \\c NSNumberFormatter doesn't perform currency conversions, it just formats numeric data. You wouldn't want one user interpreting the value "56324" as US currency and another user who's accessing the same data interpreting it as Japanese currency, simply based on each user's localization preferences. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_localizes_format(bool value) const; /** * @brief Returns the `maximum` property of `NSNumberFormatter`. - * @details The highest number allowed as input by the receiver. * @return The converted Objective-C result. */ Number maximum() const; /** * @brief Sets the `maximum` property of `NSNumberFormatter`. - * @details The highest number allowed as input by the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum(const Number& value) const; /** * @brief Returns the `maximumFractionDigits` property of `NSNumberFormatter`. - * @details The maximum number of digits after the decimal separator. By default, this property is set to \\c 0. * @return The converted Objective-C result. */ std::uint64_t maximum_fraction_digits() const; /** * @brief Sets the `maximumFractionDigits` property of `NSNumberFormatter`. - * @details The maximum number of digits after the decimal separator. By default, this property is set to \\c 0. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum_fraction_digits(std::uint64_t value) const; /** * @brief Returns the `maximumIntegerDigits` property of `NSNumberFormatter`. - * @details The maximum number of digits before the decimal separator. By default, this property is set to \\c 42. * @return The converted Objective-C result. */ std::uint64_t maximum_integer_digits() const; /** * @brief Sets the `maximumIntegerDigits` property of `NSNumberFormatter`. - * @details The maximum number of digits before the decimal separator. By default, this property is set to \\c 42. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum_integer_digits(std::uint64_t value) const; /** * @brief Returns the `maximumSignificantDigits` property of `NSNumberFormatter`. - * @details The maximum number of significant digits for the number formatter. You must set the \\c usesSignificantDigits property to \\c YES in order for this property to affect formatting behavior. By default, the maximum number of significant digits is 6. Values less than 1 are ignored. * @return The converted Objective-C result. */ std::uint64_t maximum_significant_digits() const; /** * @brief Sets the `maximumSignificantDigits` property of `NSNumberFormatter`. - * @details The maximum number of significant digits for the number formatter. You must set the \\c usesSignificantDigits property to \\c YES in order for this property to affect formatting behavior. By default, the maximum number of significant digits is 6. Values less than 1 are ignored. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum_significant_digits(std::uint64_t value) const; /** * @brief Returns the `minimum` property of `NSNumberFormatter`. - * @details The lowest number allowed as input by the receiver. * @return The converted Objective-C result. */ Number minimum() const; /** * @brief Sets the `minimum` property of `NSNumberFormatter`. - * @details The lowest number allowed as input by the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minimum(const Number& value) const; /** * @brief Returns the `minimumFractionDigits` property of `NSNumberFormatter`. - * @details The minimum number of digits after the decimal separator. By default, this property is set to \\c 0. * @return The converted Objective-C result. */ std::uint64_t minimum_fraction_digits() const; /** * @brief Sets the `minimumFractionDigits` property of `NSNumberFormatter`. - * @details The minimum number of digits after the decimal separator. By default, this property is set to \\c 0. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minimum_fraction_digits(std::uint64_t value) const; /** * @brief Returns the `minimumGroupingDigits` property of `NSNumberFormatter`. - * @details See \\c kCFNumberFormatterMinGroupingDigits in \\c CFNumberFormatter for an explanation on how minimum grouping digits is used. * @return The converted Objective-C result. */ std::int64_t minimum_grouping_digits() const; /** * @brief Sets the `minimumGroupingDigits` property of `NSNumberFormatter`. - * @details See \\c kCFNumberFormatterMinGroupingDigits in \\c CFNumberFormatter for an explanation on how minimum grouping digits is used. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minimum_grouping_digits(std::int64_t value) const; /** * @brief Returns the `minimumIntegerDigits` property of `NSNumberFormatter`. - * @details The minimum number of digits before the decimal separator. By default, this property is set to \\c 0. * @return The converted Objective-C result. */ std::uint64_t minimum_integer_digits() const; /** * @brief Sets the `minimumIntegerDigits` property of `NSNumberFormatter`. - * @details The minimum number of digits before the decimal separator. By default, this property is set to \\c 0. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minimum_integer_digits(std::uint64_t value) const; /** * @brief Returns the `minimumSignificantDigits` property of `NSNumberFormatter`. - * @details The minimum number of significant digits for the number formatter. You must set the \\c usesSignificantDigits property to \\c YES in order for this property to affect formatting behavior. By default, the minimum number of significant digits is 1. * @return The converted Objective-C result. */ std::uint64_t minimum_significant_digits() const; /** * @brief Sets the `minimumSignificantDigits` property of `NSNumberFormatter`. - * @details The minimum number of significant digits for the number formatter. You must set the \\c usesSignificantDigits property to \\c YES in order for this property to affect formatting behavior. By default, the minimum number of significant digits is 1. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minimum_significant_digits(std::uint64_t value) const; /** * @brief Returns the `minusSign` property of `NSNumberFormatter`. - * @details The string used to represent a minus sign. By default, this property is set to the minus sign (-). * @return The converted Objective-C result. */ std::string minus_sign() const; /** * @brief Sets the `minusSign` property of `NSNumberFormatter`. - * @details The string used to represent a minus sign. By default, this property is set to the minus sign (-). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_minus_sign(const std::string& value) const; /** * @brief Returns the `multiplier` property of `NSNumberFormatter`. - * @details The multiplier of the receiver. A multiplier is a factor used in conversions between numbers and strings (that is, numbers as stored and numbers as displayed). When the input value is a string, the multiplier is used to divide, and when the input value is a number, the multiplier is used to multiply. These operations allow the formatted values to be different from the values that a program manipulates internally. * @return The converted Objective-C result. */ Number multiplier() const; /** * @brief Sets the `multiplier` property of `NSNumberFormatter`. - * @details The multiplier of the receiver. A multiplier is a factor used in conversions between numbers and strings (that is, numbers as stored and numbers as displayed). When the input value is a string, the multiplier is used to divide, and when the input value is a number, the multiplier is used to multiply. These operations allow the formatted values to be different from the values that a program manipulates internally. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_multiplier(const Number& value) const; /** * @brief Returns the `negativeFormat` property of `NSNumberFormatter`. - * @details The format the receiver uses to display negative values. * @return The converted Objective-C result. */ std::string negative_format() const; /** * @brief Sets the `negativeFormat` property of `NSNumberFormatter`. - * @details The format the receiver uses to display negative values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_negative_format(const std::string& value) const; /** * @brief Returns the `negativeInfinitySymbol` property of `NSNumberFormatter`. - * @details The string used to represent a negative infinity symbol. By default, this property is set to the string "-\\u221e". * @return The converted Objective-C result. */ std::string negative_infinity_symbol() const; /** * @brief Sets the `negativeInfinitySymbol` property of `NSNumberFormatter`. - * @details The string used to represent a negative infinity symbol. By default, this property is set to the string "-\\u221e". * @param value Argument converted to the Objective-C parameter of the same role. */ void set_negative_infinity_symbol(const std::string& value) const; /** * @brief Returns the `negativePrefix` property of `NSNumberFormatter`. - * @details The string the receiver uses as a prefix for negative values. * @return The converted Objective-C result. */ std::string negative_prefix() const; /** * @brief Sets the `negativePrefix` property of `NSNumberFormatter`. - * @details The string the receiver uses as a prefix for negative values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_negative_prefix(const std::string& value) const; /** * @brief Returns the `negativeSuffix` property of `NSNumberFormatter`. - * @details The string the receiver uses as a suffix for negative values. * @return The converted Objective-C result. */ std::string negative_suffix() const; /** * @brief Sets the `negativeSuffix` property of `NSNumberFormatter`. - * @details The string the receiver uses as a suffix for negative values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_negative_suffix(const std::string& value) const; /** * @brief Returns the `nilSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a \\c nil value. By default, this property is set to an empty string (""). * @return The converted Objective-C result. */ std::string nil_symbol() const; /** * @brief Sets the `nilSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a \\c nil value. By default, this property is set to an empty string (""). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_nil_symbol(const std::string& value) const; /** * @brief Returns the `notANumberSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a NaN ("not a number") value. By default, this property is set to the string "NaN". * @return The converted Objective-C result. */ std::string not_a_number_symbol() const; /** * @brief Sets the `notANumberSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a NaN ("not a number") value. By default, this property is set to the string "NaN". * @param value Argument converted to the Objective-C parameter of the same role. */ void set_not_a_number_symbol(const std::string& value) const; /** * @brief Returns the `numberStyle` property of `NSNumberFormatter`. - * @details The number style used by the receiver. Styles are essentially predetermined sets of values for certain properties. Examples of number-formatter styles are those used for decimal values, percentage values, and currency. * @return The converted Objective-C result. */ NumberFormatterStyle number_style() const; /** * @brief Sets the `numberStyle` property of `NSNumberFormatter`. - * @details The number style used by the receiver. Styles are essentially predetermined sets of values for certain properties. Examples of number-formatter styles are those used for decimal values, percentage values, and currency. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_number_style(NumberFormatterStyle value) const; /** * @brief Returns the `paddingCharacter` property of `NSNumberFormatter`. - * @details The string that the receiver uses to pad numbers in the formatted string representation. * @return The converted Objective-C result. */ std::string padding_character() const; /** * @brief Sets the `paddingCharacter` property of `NSNumberFormatter`. - * @details The string that the receiver uses to pad numbers in the formatted string representation. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_padding_character(const std::string& value) const; /** * @brief Returns the `paddingPosition` property of `NSNumberFormatter`. - * @details The padding position used by the receiver. * @return The converted Objective-C result. */ NumberFormatterPadPosition padding_position() const; /** * @brief Sets the `paddingPosition` property of `NSNumberFormatter`. - * @details The padding position used by the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_padding_position(NumberFormatterPadPosition value) const; /** * @brief Returns the `partialStringValidationEnabled` property of `NSNumberFormatter`. - * @details Determines whether partial string validation is enabled for the receiver. * @return The converted Objective-C result. */ bool is_partial_string_validation_enabled() const; /** * @brief Sets the `partialStringValidationEnabled` property of `NSNumberFormatter`. - * @details Determines whether partial string validation is enabled for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_partial_string_validation_enabled(bool value) const; /** * @brief Returns the `perMillSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a per-mill (per-thousand) symbol. By default, this property is set to the per mille sign (\\u2030). * @return The converted Objective-C result. */ std::string per_mill_symbol() const; /** * @brief Sets the `perMillSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a per-mill (per-thousand) symbol. By default, this property is set to the per mille sign (\\u2030). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_per_mill_symbol(const std::string& value) const; /** * @brief Returns the `percentSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a percent symbol. By default, this property is set to the percent sign (\%). * @return The converted Objective-C result. */ std::string percent_symbol() const; /** * @brief Sets the `percentSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a percent symbol. By default, this property is set to the percent sign (\%). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_percent_symbol(const std::string& value) const; /** * @brief Returns the `plusSign` property of `NSNumberFormatter`. - * @details The string used to represent a plus sign. By default, this property is set to the plus sign (+). * @return The converted Objective-C result. */ std::string plus_sign() const; /** * @brief Sets the `plusSign` property of `NSNumberFormatter`. - * @details The string used to represent a plus sign. By default, this property is set to the plus sign (+). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_plus_sign(const std::string& value) const; /** * @brief Returns the `positiveFormat` property of `NSNumberFormatter`. - * @details The format the receiver uses to display positive values. * @return The converted Objective-C result. */ std::string positive_format() const; /** * @brief Sets the `positiveFormat` property of `NSNumberFormatter`. - * @details The format the receiver uses to display positive values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_positive_format(const std::string& value) const; /** * @brief Returns the `positiveInfinitySymbol` property of `NSNumberFormatter`. - * @details The string used to represent a positive infinity symbol. By default, this property is set to the string "+\\u221e". * @return The converted Objective-C result. */ std::string positive_infinity_symbol() const; /** * @brief Sets the `positiveInfinitySymbol` property of `NSNumberFormatter`. - * @details The string used to represent a positive infinity symbol. By default, this property is set to the string "+\\u221e". * @param value Argument converted to the Objective-C parameter of the same role. */ void set_positive_infinity_symbol(const std::string& value) const; /** * @brief Returns the `positivePrefix` property of `NSNumberFormatter`. - * @details The string the receiver uses as the prefix for positive values. * @return The converted Objective-C result. */ std::string positive_prefix() const; /** * @brief Sets the `positivePrefix` property of `NSNumberFormatter`. - * @details The string the receiver uses as the prefix for positive values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_positive_prefix(const std::string& value) const; /** * @brief Returns the `positiveSuffix` property of `NSNumberFormatter`. - * @details The string the receiver uses as the suffix for positive values. * @return The converted Objective-C result. */ std::string positive_suffix() const; /** * @brief Sets the `positiveSuffix` property of `NSNumberFormatter`. - * @details The string the receiver uses as the suffix for positive values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_positive_suffix(const std::string& value) const; /** * @brief Returns the `roundingBehavior` property of `NSNumberFormatter`. - * @details The rounding behavior used by the receiver. * @return The converted Objective-C result. */ DecimalNumberHandler rounding_behavior() const; /** * @brief Sets the `roundingBehavior` property of `NSNumberFormatter`. - * @details The rounding behavior used by the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_rounding_behavior(const DecimalNumberHandler& value) const; /** * @brief Returns the `roundingIncrement` property of `NSNumberFormatter`. - * @details The rounding increment used by the receiver. * @return The converted Objective-C result. */ Number rounding_increment() const; /** * @brief Sets the `roundingIncrement` property of `NSNumberFormatter`. - * @details The rounding increment used by the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_rounding_increment(const Number& value) const; /** * @brief Returns the `roundingMode` property of `NSNumberFormatter`. - * @details The rounding mode used by the receiver. * @return The converted Objective-C result. */ NumberFormatterRoundingMode rounding_mode() const; /** * @brief Sets the `roundingMode` property of `NSNumberFormatter`. - * @details The rounding mode used by the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_rounding_mode(NumberFormatterRoundingMode value) const; /** * @brief Returns the `secondaryGroupingSize` property of `NSNumberFormatter`. - * @details The secondary grouping size of the receiver. Some locales allow the specification of another grouping size for larger numbers. For example, some locales may represent a number such as 61, 242, 378.46 (as in the United States) as 6,12,42,378.46. In this case, the secondary grouping size (covering the groups of digits furthest from the decimal point) is 2. * @return The converted Objective-C result. */ std::uint64_t secondary_grouping_size() const; /** * @brief Sets the `secondaryGroupingSize` property of `NSNumberFormatter`. - * @details The secondary grouping size of the receiver. Some locales allow the specification of another grouping size for larger numbers. For example, some locales may represent a number such as 61, 242, 378.46 (as in the United States) as 6,12,42,378.46. In this case, the secondary grouping size (covering the groups of digits furthest from the decimal point) is 2. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_secondary_grouping_size(std::uint64_t value) const; /** * @brief Returns the `textAttributesForNegativeInfinity` property of `NSNumberFormatter`. - * @details The text attributes used to display the negative infinity symbol. This property is a dictionary that contains the text attributes used to display the negative infinity string. * @return The converted Objective-C result. */ std::map text_attributes_for_negative_infinity() const; /** * @brief Sets the `textAttributesForNegativeInfinity` property of `NSNumberFormatter`. - * @details The text attributes used to display the negative infinity symbol. This property is a dictionary that contains the text attributes used to display the negative infinity string. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_attributes_for_negative_infinity(const std::map& value) const; /** * @brief Returns the `textAttributesForNegativeValues` property of `NSNumberFormatter`. - * @details The text attributes to be used in displaying negative values. This property is a dictionary that contains the attributes used to display negative values. * @return The converted Objective-C result. */ std::map text_attributes_for_negative_values() const; /** * @brief Sets the `textAttributesForNegativeValues` property of `NSNumberFormatter`. - * @details The text attributes to be used in displaying negative values. This property is a dictionary that contains the attributes used to display negative values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_attributes_for_negative_values(const std::map& value) const; /** * @brief Returns the `textAttributesForNil` property of `NSNumberFormatter`. - * @details The text attributes used to display the \\c nil symbol. * @return The converted Objective-C result. */ std::map text_attributes_for_nil() const; /** * @brief Sets the `textAttributesForNil` property of `NSNumberFormatter`. - * @details The text attributes used to display the \\c nil symbol. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_attributes_for_nil(const std::map& value) const; /** * @brief Returns the `textAttributesForNotANumber` property of `NSNumberFormatter`. - * @details The text attributes used to display the NaN ("not a number") string. * @return The converted Objective-C result. */ std::map text_attributes_for_not_a_number() const; /** * @brief Sets the `textAttributesForNotANumber` property of `NSNumberFormatter`. - * @details The text attributes used to display the NaN ("not a number") string. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_attributes_for_not_a_number(const std::map& value) const; /** * @brief Returns the `textAttributesForPositiveInfinity` property of `NSNumberFormatter`. - * @details The text attributes used to display the positive infinity symbol. This property is a dictionary that contains the text attributes used to display the positive infinity string. * @return The converted Objective-C result. */ std::map text_attributes_for_positive_infinity() const; /** * @brief Sets the `textAttributesForPositiveInfinity` property of `NSNumberFormatter`. - * @details The text attributes used to display the positive infinity symbol. This property is a dictionary that contains the text attributes used to display the positive infinity string. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_attributes_for_positive_infinity(const std::map& value) const; /** * @brief Returns the `textAttributesForPositiveValues` property of `NSNumberFormatter`. - * @details The text attributes to be used in displaying positive values. This property is a dictionary that contains the attributes used to display positive values. * @return The converted Objective-C result. */ std::map text_attributes_for_positive_values() const; /** * @brief Sets the `textAttributesForPositiveValues` property of `NSNumberFormatter`. - * @details The text attributes to be used in displaying positive values. This property is a dictionary that contains the attributes used to display positive values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_attributes_for_positive_values(const std::map& value) const; /** * @brief Returns the `textAttributesForZero` property of `NSNumberFormatter`. - * @details The text attributes used to display a zero value. This property is a dictionary that contains the text attributes used to display zero values. * @return The converted Objective-C result. */ std::map text_attributes_for_zero() const; /** * @brief Sets the `textAttributesForZero` property of `NSNumberFormatter`. - * @details The text attributes used to display a zero value. This property is a dictionary that contains the text attributes used to display zero values. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_attributes_for_zero(const std::map& value) const; /** * @brief Returns the `thousandSeparator` property of `NSNumberFormatter`. - * @details The character the receiver uses as a thousand separator. If you don't have thousand separators enabled through any other means (such as \\c format), using this method enables them. This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @return The converted Objective-C result. */ std::string thousand_separator() const; /** * @brief Sets the `thousandSeparator` property of `NSNumberFormatter`. - * @details The character the receiver uses as a thousand separator. If you don't have thousand separators enabled through any other means (such as \\c format), using this method enables them. This method is for use with formatters using \\c NSNumberFormatterBehavior10_0 behavior. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_thousand_separator(const std::string& value) const; /** * @brief Returns the `usesGroupingSeparator` property of `NSNumberFormatter`. - * @details Determines whether the receiver displays the group separator. * @return The converted Objective-C result. */ bool uses_grouping_separator() const; /** * @brief Sets the `usesGroupingSeparator` property of `NSNumberFormatter`. - * @details Determines whether the receiver displays the group separator. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_uses_grouping_separator(bool value) const; /** * @brief Returns the `usesSignificantDigits` property of `NSNumberFormatter`. - * @details A Boolean value indicating whether the formatter uses minimum and maximum significant digits when formatting numbers. The \\c NSNumberFormatter class has two ways of determining how many digits to represent: using integer and fraction digits and using significant digits. When this property is set to \\c NO, numbers are formatted according to whether you want them formatted as fractions or as integers. This property is \\c NO by default. Set this property to \\c YES to format numbers according to the significant digits configuration specified by the \\c minimumSignificantDigits and \\c maximumSignificantDigits properties. By default, the minimum number of significant digits is 1, and the maximum number of significant digits is 6. When a number formatter is configured to use significant digits, it ignores any minimum or maximum values used to set integer or fraction digits. * @return The converted Objective-C result. */ bool uses_significant_digits() const; /** * @brief Sets the `usesSignificantDigits` property of `NSNumberFormatter`. - * @details A Boolean value indicating whether the formatter uses minimum and maximum significant digits when formatting numbers. The \\c NSNumberFormatter class has two ways of determining how many digits to represent: using integer and fraction digits and using significant digits. When this property is set to \\c NO, numbers are formatted according to whether you want them formatted as fractions or as integers. This property is \\c NO by default. Set this property to \\c YES to format numbers according to the significant digits configuration specified by the \\c minimumSignificantDigits and \\c maximumSignificantDigits properties. By default, the minimum number of significant digits is 1, and the maximum number of significant digits is 6. When a number formatter is configured to use significant digits, it ignores any minimum or maximum values used to set integer or fraction digits. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_uses_significant_digits(bool value) const; /** * @brief Returns the `zeroSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a zero value. If not specified, zero values are formatted normally. You might, for example, set this property to \\c "-" in a spreadsheet used for accounting. * @return The converted Objective-C result. */ std::string zero_symbol() const; /** * @brief Sets the `zeroSymbol` property of `NSNumberFormatter`. - * @details The string used to represent a zero value. If not specified, zero values are formatted normally. You might, for example, set this property to \\c "-" in a spreadsheet used for accounting. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_zero_symbol(const std::string& value) const; diff --git a/include/generated/open_panel.h b/include/generated/open_panel.h index 59591056..086a9597 100644 --- a/include/generated/open_panel.h +++ b/include/generated/open_panel.h @@ -74,25 +74,21 @@ namespace cocoon void set_allows_multiple_selection(bool value) const; /** * @brief Returns the `canChooseDirectories` property of `NSOpenPanel`. - * @details Whether or not the user can choose directories in open the panel. \@discussion In macOS 27 and later, 'canChooseDirectories' is updated when you set 'allowedContentTypes' or set 'treatsFilePackagesAsDirectories'. If 'allowedContentTypes' contains a type that conforms to 'UTTypeDirectory' then 'canChooseDirectories' is set to 'YES'. If 'allowedContentTypes' contains a type that conforms to 'UTTypePackage' and 'treatsFilePackagesAsDirectories' is 'YES', then 'canChooseDirectories' is set to 'YES'. By default 'canChooseDirectories' is 'NO'. In general you will only need to set 'canChooseDirectories' to 'YES' when 'allowedContentTypes' is '[]' (the empty array). If you set 'canChooseDirectories' to 'YES' then set 'allowedContentTypes' to '[]', 'canChooseDirectories' will still be 'YES'. However, if you reset 'allowedContentTypes' from non-empty to empty, then that will also reset 'canChooseDirectories' to 'NO', the default value. In short, setting 'allowedContentTypes' to '[]' keeps your setting or overrides the automatic system setting. If unsure, you can always set 'canChooseDirectories' after setting 'allowedContentTypes'. * @return The converted Objective-C result. */ bool can_choose_directories() const; /** * @brief Sets the `canChooseDirectories` property of `NSOpenPanel`. - * @details Whether or not the user can choose directories in open the panel. \@discussion In macOS 27 and later, 'canChooseDirectories' is updated when you set 'allowedContentTypes' or set 'treatsFilePackagesAsDirectories'. If 'allowedContentTypes' contains a type that conforms to 'UTTypeDirectory' then 'canChooseDirectories' is set to 'YES'. If 'allowedContentTypes' contains a type that conforms to 'UTTypePackage' and 'treatsFilePackagesAsDirectories' is 'YES', then 'canChooseDirectories' is set to 'YES'. By default 'canChooseDirectories' is 'NO'. In general you will only need to set 'canChooseDirectories' to 'YES' when 'allowedContentTypes' is '[]' (the empty array). If you set 'canChooseDirectories' to 'YES' then set 'allowedContentTypes' to '[]', 'canChooseDirectories' will still be 'YES'. However, if you reset 'allowedContentTypes' from non-empty to empty, then that will also reset 'canChooseDirectories' to 'NO', the default value. In short, setting 'allowedContentTypes' to '[]' keeps your setting or overrides the automatic system setting. If unsure, you can always set 'canChooseDirectories' after setting 'allowedContentTypes'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_can_choose_directories(bool value) const; /** * @brief Returns the `canChooseFiles` property of `NSOpenPanel`. - * @details Whether or not the user can choose files in the open panel. \@discussion In macOS 27 and later, 'canChooseFiles' is updated when you set 'allowedContentTypes' or set 'treatsFilePackagesAsDirectories'. If 'allowedContentTypes' contains a type that does not conform to 'UTTypeDirectory' then 'canChooseFiles' is set to 'YES'. If 'allowedContentTypes' contains a type that conforms to 'UTTypePackage' and 'treatsFilePackagesAsDirectories' is 'NO', then 'canChooseFiles' is set to 'YES. By default 'canChooseFiles' is 'YES'. In general you will only need to set 'canChooseFiles' to 'NO' when 'allowedContentTypes' is '[]' (the empty array). If you set 'canChooseFiles' to 'NO' then set 'allowedContentTypes' to '[]', 'canChooseFiles' will still be 'NO'. However, if you reset 'allowedContentTypes' from non-empty to empty, then that will also reset 'canChooseFiles' to 'YES', the default value. In short, setting 'allowedContentTypes' to '[]' keeps your setting or overrides the automatic system setting. If unsure, you can always set 'canChooseFiles' after setting 'allowedContentTypes'. * @return The converted Objective-C result. */ bool can_choose_files() const; /** * @brief Sets the `canChooseFiles` property of `NSOpenPanel`. - * @details Whether or not the user can choose files in the open panel. \@discussion In macOS 27 and later, 'canChooseFiles' is updated when you set 'allowedContentTypes' or set 'treatsFilePackagesAsDirectories'. If 'allowedContentTypes' contains a type that does not conform to 'UTTypeDirectory' then 'canChooseFiles' is set to 'YES'. If 'allowedContentTypes' contains a type that conforms to 'UTTypePackage' and 'treatsFilePackagesAsDirectories' is 'NO', then 'canChooseFiles' is set to 'YES. By default 'canChooseFiles' is 'YES'. In general you will only need to set 'canChooseFiles' to 'NO' when 'allowedContentTypes' is '[]' (the empty array). If you set 'canChooseFiles' to 'NO' then set 'allowedContentTypes' to '[]', 'canChooseFiles' will still be 'NO'. However, if you reset 'allowedContentTypes' from non-empty to empty, then that will also reset 'canChooseFiles' to 'YES', the default value. In short, setting 'allowedContentTypes' to '[]' keeps your setting or overrides the automatic system setting. If unsure, you can always set 'canChooseFiles' after setting 'allowedContentTypes'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_can_choose_files(bool value) const; diff --git a/include/generated/operation.h b/include/generated/operation.h index 599823d5..55352d7a 100644 --- a/include/generated/operation.h +++ b/include/generated/operation.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSOperation` (Foundation). - * @details An abstract class that represents the code and data associated with a single task. Because the ''Operation'' class is an abstract class, you do not use it directly but instead subclass or use one of the system-defined subclasses (''NSInvocationOperation'' or ''BlockOperation'') to perform the actual task. Despite being abstract, the base implementation of ''Operation'' does include significant logic to coordinate the safe execution of your task. The presence of this built-in logic allows you to focus on the actual implementation of your task, rather than on the glue code needed to ensure it works correctly with other system objects. An operation object is a single-shot object—that is, it executes its task once and cannot be used to execute it again. You typically execute operations by adding them to an operation queue (an instance of the ''OperationQueue'' class). An operation queue executes its operations either directly, by running them on secondary threads, or indirectly using the 'libdispatch' library (also known as Grand Central Dispatch). For more information about how queues execute operations, see ''OperationQueue''. If you do not want to use an operation queue, you can execute an operation yourself by calling its ''start()'' method directly from your code. Executing operations manually does put more of a burden on your code, because starting an operation that is not in the ready state triggers an exception. The ''isReady'' property reports on the operation's readiness. \#\#\# Operation Dependencies Dependencies are a convenient way to execute operations in a specific order. You can add and remove dependencies for an operation using the ''addDependency(:)'' and ''removeDependency(:)'' methods. By default, an operation object that has dependencies is not considered ready until all of its dependent operation objects have finished executing. Once the last dependent operation finishes, however, the operation object becomes ready and able to execute. The dependencies supported by 'NSOperation' make no distinction about whether a dependent operation finished successfully or unsuccessfully. (In other words, canceling an operation similarly marks it as finished.) It is up to you to determine whether an operation with dependencies should proceed in cases where its dependent operations were cancelled or did not complete their task successfully. This may require you to incorporate some additional error tracking capabilities into your operation objects. \#\#\# KVO-Compliant Properties The 'NSOperation' class is key-value coding (KVC) and key-value observing (KVO) compliant for several of its properties. As needed, you can observe these properties to control other parts of your application. To observe the properties, use the following key paths: - 'isCancelled' - read-only - 'isAsynchronous' - read-only - 'isExecuting' - read-only - 'isFinished' - read-only - 'isReady' - read-only - 'dependencies' - read-only - 'queuePriority' - readable and writable - 'completionBlock' - readable and writable Although you can attach observers to these properties, you should not use Cocoa bindings to bind them to elements of your application's user interface. Code associated with your user interface typically must execute only in your application's main thread. Because an operation may execute in any thread, KVO notifications associated with that operation may similarly occur in any thread. If you provide custom implementations for any of the preceding properties, your implementations must maintain KVC and KVO compliance. If you define additional properties for your 'NSOperation' objects, it is recommended that you make those properties KVC and KVO compliant as well. For information on how to support key-value coding, see [Key-Value Coding Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/KeyValueCoding/index.html\#//apple_ref/doc/uid/10000107i). For information on how to support key-value observing, see [Key-Value Observing Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html\#//apple_ref/doc/uid/10000177i). \#\#\# Multicore Considerations The 'NSOperation' class is itself multicore aware. It is therefore safe to call the methods of an 'NSOperation' object from multiple threads without creating additional locks to synchronize access to the object. This behavior is necessary because an operation typically runs in a separate thread from the one that created and is monitoring it. When you subclass 'NSOperation', you must make sure that any overridden methods remain safe to call from multiple threads. If you implement custom methods in your subclass, such as custom data accessors, you must also make sure those methods are thread-safe. Thus, access to any data variables in the operation must be synchronized to prevent potential data corruption. For more information about synchronization, see [Threading Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Multithreading/Introduction/Introduction.html\#//apple_ref/doc/uid/10000057i). \#\#\# Asynchronous Versus Synchronous Operations If you plan on executing an operation object manually, instead of adding it to a queue, you can design your operation to execute in a synchronous or asynchronous manner. Operation objects are synchronous by default. In a synchronous operation, the operation object does not create a separate thread on which to run its task. When you call the ''start()'' method of a synchronous operation directly from your code, the operation executes immediately in the current thread. By the time the ''start()'' method of such an object returns control to the caller, the task itself is complete. When you call the ''start()'' method of an asynchronous operation, that method may return before the corresponding task is completed. An asynchronous operation object is responsible for scheduling its task on a separate thread. The operation could do that by starting a new thread directly, by calling an asynchronous method, or by submitting a block to a dispatch queue for execution. It does not actually matter if the operation is ongoing when control returns to the caller, only that it could be ongoing. If you always plan to use queues to execute your operations, it is simpler to define them as synchronous. If you execute operations manually, though, you might want to define your operation objects as asynchronous. Defining an asynchronous operation requires more work, because you have to monitor the ongoing state of your task and report changes in that state using KVO notifications. But defining asynchronous operations is useful in cases where you want to ensure that a manually executed operation does not block the calling thread. When you add an operation to an operation queue, the queue ignores the value of the ''isAsynchronous'' property and always calls the ''start()'' method from a separate thread. Therefore, if you always run operations by adding them to an operation queue, there is no reason to make them asynchronous. For information on how to define both synchronous and asynchronous operations, see the subclassing notes. \#\#\# Subclassing Notes The 'NSOperation' class provides the basic logic to track the execution state of your operation but otherwise must be subclassed to do any real work. How you create your subclass depends on whether your operation is designed to execute concurrently or non-concurrently. \#\#\#\# Methods to Override For non-concurrent operations, you typically override only one method: - ''main()'' Into this method, you place the code needed to perform the given task. Of course, you should also define a custom initialization method to make it easier to create instances of your custom class. You might also want to define getter and setter methods to access the data from the operation. However, if you do define custom getter and setter methods, you must make sure those methods can be called safely from multiple threads. If you are creating a concurrent operation, you need to override the following methods and properties at a minimum: - ''start()'' - ''isAsynchronous'' - ''isExecuting'' - ''isFinished'' In a concurrent operation, your ''start()'' method is responsible for starting the operation in an asynchronous manner. Whether you spawn a thread or call an asynchronous function, you do it from this method. Upon starting the operation, your ''start()'' method should also update the execution state of the operation as reported by the ''isExecuting'' property. You do this by sending out KVO notifications for the ''isExecuting'' key path, which lets interested clients know that the operation is now running. Your ''isExecuting'' property must also provide the status in a thread-safe manner. Upon completion or cancellation of its task, your concurrent operation object must generate KVO notifications for both the 'isExecuting' and 'isFinished' key paths to mark the final change of state for your operation. (In the case of cancellation, it is still important to update the 'isFinished' key path, even if the operation did not completely finish its task. Queued operations must report that they are finished before they can be removed from a queue.) In addition to generating KVO notifications, your overrides of the ''isExecuting'' and ''isFinished'' properties should also continue to report accurate values based on the state of your operation. For additional information and guidance on how to define concurrent operations, see [Concurrency Programming Guide](https://developer.apple.com/library/archive/documentation/General/Conceptual/ConcurrencyProgrammingGuide/Introduction/Introduction.html\#//apple_ref/doc/uid/TP40008091). > Important: > At no time in your ''start()'' method should you ever call 'super'. When you define a concurrent operation, you take it upon yourself to provide the same behavior that the default ''start()'' method provides, which includes starting the task and generating the appropriate KVO notifications. Your ''start()'' method should also check to see if the operation itself was cancelled before actually starting the task. For more information about cancellation semantics, see \. Even for concurrent operations, there should be little need to override methods other than those described above. However, if you customize the dependency features of operations, you might have to override additional methods and provide additional KVO notifications. In the case of dependencies, this would likely only require providing notifications for the 'isReady' key path. Because the ''dependencies'' property contains the list of dependent operations, changes to it are already handled by the default 'NSOperation' class. \#\#\#\# Maintaining Operation Object States Operation objects maintain state information internally to determine when it is safe to execute and also to notify external clients of the progression through the operation's life cycle. Your custom subclasses maintains this state information to ensure the correct execution of operations in your code. The key paths associated with an operation's states are: - term 'isReady': The 'isReady' key path lets clients know when an operation is ready to execute. The ''isReady'' property contains the value 'true' when the operation is ready to execute now or 'false' if there are still unfinished operations on which it is dependent. In most cases, you do not have to manage the state of this key path yourself. If the readiness of your operations is determined by factors other than dependent operations, however—such as by some external condition in your program—you can provide your own implementation of the ''isReady'' property and track your operation's readiness yourself. It is often simpler though just to create operation objects only when your external state allows it. In macOS 10.6 and later, if you cancel an operation while it is waiting on the completion of one or more dependent operations, those dependencies are thereafter ignored and the value of this property is updated to reflect that it is now ready to run. This behavior gives an operation queue the chance to flush cancelled operations out of its queue more quickly. - term 'isExecuting': The 'isExecuting' key path lets clients know whether the operation is actively working on its assigned task. The ''isExecuting'' property must report the value 'true' if the operation is working on its task or 'false' if it is not. If you replace the ''start()'' method of your operation object, you must also replace the ''isExecuting'' property and generate KVO notifications when the execution state of your operation changes. - term 'isFinished': The 'isFinished' key path lets clients know that an operation finished its task successfully or was cancelled and is exiting. An operation object does not clear a dependency until the value at the 'isFinished' key path changes to 'true'. Similarly, an operation queue does not dequeue an operation until the ''isFinished'' property contains the value 'true'. Thus, marking operations as finished is critical to keeping queues from backing up with in-progress or cancelled operations. If you replace the ''start()'' method or your operation object, you must also replace the ''isFinished'' property and generate KVO notifications when the operation finishes executing or is cancelled. - term 'isCancelled': The 'isCancelled' key path lets clients know that the cancellation of an operation was requested. Support for cancellation is voluntary but encouraged and your own code should not have to send KVO notifications for this key path. The handling of cancellation notices in an operation is described in more detail in \. \#\#\#\# Responding to the Cancel Command Once you add an operation to a queue, the operation is out of your hands. The queue takes over and handles the scheduling of that task. However, if you decide later that you do not want to execute the operation after all—because the user pressed a cancel button in a progress panel or quit the application, for example—you can cancel the operation to prevent it from consuming CPU time needlessly. You do this by calling the ''cancel()'' method of the operation object itself or by calling the ''OperationQueue/cancelAllOperations()'' method of the ''OperationQueue'' class. Canceling an operation does not immediately force it to stop what it is doing. Although respecting the value in the ''isCancelled'' property is expected of all operations, your code must explicitly check the value in this property and abort as needed. The default implementation of 'NSOperation' includes checks for cancellation. For example, if you cancel an operation before its ''start()'' method is called, the ''start()'' method exits without starting the task. > Note: > In macOS 10.6 and later, if you call the ''cancel()'' method on an operation that is in an operation queue and has unfinished dependent operations, those dependent operations are subsequently ignored. Because the operation is already cancelled, this behavior allows the queue to call the operation's ''start()'' method to remove the operation from the queue without calling its ''main()'' method. If you call the ''cancel()'' method on an operation that is not in a queue, the operation is immediately marked as being cancelled. In each case, marking the operation as ready or finished results in the generation of the appropriate KVO notifications. You should always support cancellation semantics in any custom code you write. In particular, your main task code should periodically check the value of the ''isCancelled'' property. If the property reports the value \, your operation object should clean up and exit as quickly as possible. If you implement a custom ''start()'' method, that method should include early checks for cancellation and behave appropriately. Your custom ''start()'' method must be prepared to handle this type of early cancellation. In addition to simply exiting when an operation is cancelled, it is also important that you move a cancelled operation to the appropriate final state. Specifically, if you manage the values for the ''isFinished'' and ''isExecuting'' properties yourself (perhaps because you are implementing a concurrent operation), you must update those properties accordingly. Specifically, you must change the value returned by ''isFinished'' to \ and the value returned by ''isExecuting'' to \. You must make these changes even if the operation was cancelled before it started executing. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,123 +46,102 @@ namespace cocoon explicit Operation(Adopt adopt); /** * @brief Calls `-[NSOperation addDependency:]`. - * @details Makes the receiver dependent on the completion of the specified operation. The receiver is not considered ready to execute until all of its dependent operations have finished executing. If the receiver is already executing its task, adding dependencies has no practical effect. This method may change the 'isReady' and 'dependencies' properties of the receiver. It is a programmer error to create any circular dependencies among a set of operations. Doing so can cause a deadlock among the operations and may freeze your program. - Parameter op: The operation on which the receiver should depend. The same dependency should not be added more than once to the receiver, and the results of doing so are undefined. * @param op Argument converted to the Objective-C parameter of the same role. */ void add_dependency(const Operation& op) const; /** * @brief Calls `-[NSOperation cancel]`. - * @details Advises the operation object that it should stop executing its task. This method does not force your operation code to stop. Instead, it updates the object's internal flags to reflect the change in state. If the operation has already finished executing, this method has no effect. Canceling an operation that is currently in an operation queue, but not yet executing, makes it possible to remove the operation from the queue sooner than usual. */ void cancel() const; /** * @brief Calls `-[NSOperation main]`. - * @details Performs the receiver's non-concurrent task. The default implementation of this method does nothing. You should override this method to perform the desired task. In your implementation, do not invoke 'super'. This method will automatically execute within an autorelease pool provided by 'NSOperation', so you do not need to create your own autorelease pool block in your implementation. If you are implementing a concurrent operation, you are not required to override this method but may do so if you plan to call it from your custom ''start'' method. */ void main_() const; /** * @brief Calls `-[NSOperation removeDependency:]`. - * @details Removes the receiver's dependence on the specified operation. This method may change the 'isReady' and 'dependencies' properties of the receiver. - Parameter op: The dependent operation to be removed from the receiver. * @param op Argument converted to the Objective-C parameter of the same role. */ void remove_dependency(const Operation& op) const; /** * @brief Calls `-[NSOperation start]`. - * @details Begins the execution of the operation. The default implementation of this method updates the execution state of the operation and calls the receiver's ''main'' method. This method also performs several checks to ensure that the operation can actually run. For example, if the receiver was cancelled or is already finished, this method simply returns without calling ''main''. If the operation is currently executing or is not ready to execute, this method throws an 'NSInvalidArgumentException' exception. If you are implementing a concurrent operation, you must override this method and use it to initiate your operation. Your custom implementation must not call 'super' at any time. In addition to configuring the execution environment for your task, your implementation of this method must also track the state of the operation and provide appropriate state transitions. When the operation executes and subsequently finishes its work, it should generate KVO notifications for the 'isExecuting' and 'isFinished' key paths respectively. You can call this method explicitly if you want to execute your operations manually. However, it is a programmer error to call this method on an operation object that is already in an operation queue or to queue the operation after calling this method. Once you add an operation object to a queue, the queue assumes all responsibility for it. */ void start() const; /** * @brief Calls `-[NSOperation waitUntilFinished]`. - * @details Blocks execution of the current thread until the operation object finishes its task. An operation object must never call this method on itself and should avoid calling it on any operations submitted to the same operation queue as itself. Doing so can cause the operation to deadlock. It is generally safe to call this method on an operation that is in a different operation queue, although it is still possible to create deadlocks if each operation waits on the other. */ void wait_until_finished() const; /** * @brief Returns the `asynchronous` property of `NSOperation`. - * @details A Boolean value indicating whether the operation executes its task asynchronously. The default value of this property is 'NO'. When implementing an asynchronous operation object, you must implement this property and return 'YES'. * @return The converted Objective-C result. */ bool is_asynchronous() const; /** * @brief Returns the `cancelled` property of `NSOperation`. - * @details A Boolean value indicating whether the operation has been cancelled. The default value of this property is 'NO'. Calling the ''cancel'' method of this object sets the value of this property to 'YES'. Once canceled, an operation must move to the finished state. Canceling an operation does not actively stop the receiver's code from executing. An operation object is responsible for calling this method periodically and stopping itself if the method returns 'YES'. You should always check the value of this property before doing any work towards accomplishing the operation's task, which typically means checking it at the beginning of your custom ''main'' method. It is possible for an operation to be cancelled before it begins executing or at any time while it is executing. * @return The converted Objective-C result. */ bool is_cancelled() const; /** * @brief Returns the `completionBlock` property of `NSOperation`. - * @details The block to execute after the operation's main task is completed. The completion block takes no parameters and has no return value. The exact execution context for your completion block is not guaranteed but is typically a secondary thread. Therefore, you should not use this block to do any work that requires a very specific execution context. Instead, you should shunt that work to your application's main thread or to the specific thread that is capable of doing it. Because the completion block executes after the operation indicates it has finished its task, you must not use a completion block to queue additional work considered to be part of that task. A finished operation may finish either because it was cancelled or because it successfully completed its task. You should take that fact into account when writing your block code. In iOS 8 and later and macOS 10.10 and later, this property is set to 'nil' after the completion block begins executing. * @return The converted Objective-C result. */ std::function completion_block() const; /** * @brief Sets the `completionBlock` property of `NSOperation`. - * @details The block to execute after the operation's main task is completed. The completion block takes no parameters and has no return value. The exact execution context for your completion block is not guaranteed but is typically a secondary thread. Therefore, you should not use this block to do any work that requires a very specific execution context. Instead, you should shunt that work to your application's main thread or to the specific thread that is capable of doing it. Because the completion block executes after the operation indicates it has finished its task, you must not use a completion block to queue additional work considered to be part of that task. A finished operation may finish either because it was cancelled or because it successfully completed its task. You should take that fact into account when writing your block code. In iOS 8 and later and macOS 10.10 and later, this property is set to 'nil' after the completion block begins executing. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_completion_block(std::function value) const; /** * @brief Returns the `concurrent` property of `NSOperation`. - * @details A Boolean value indicating whether the operation executes its task asynchronously. Use the ''asynchronous'' property instead. The default value of this property is 'NO'. In macOS 10.6 and later, operation queues ignore the value in this property and always start operations on a separate thread. * @return The converted Objective-C result. */ bool is_concurrent() const; /** * @brief Returns the `dependencies` property of `NSOperation`. - * @details An array of the operation objects that must finish executing before the current object can begin executing. This property contains an array of 'NSOperation' objects. To add an object to this array, use the ''addDependency:'' method. An operation object must not execute until all of its dependent operations finish executing. Operations are not removed from this dependency list as they finish executing. You can use this list to track all dependent operations, including those that have already finished executing. The only way to remove an operation from this list is to use the ''removeDependency:'' method. * @return The converted Objective-C result. */ std::vector dependencies() const; /** * @brief Returns the `executing` property of `NSOperation`. - * @details A Boolean value indicating whether the operation is currently executing. The value of this property is 'YES' if the operation is currently executing its main task or 'NO' if it is not. When implementing a concurrent operation object, you must override the implementation of this property so that you can return the execution state of your operation. In your custom implementation, you must generate KVO notifications for the 'isExecuting' key path whenever the execution state of your operation object changes. * @return The converted Objective-C result. */ bool is_executing() const; /** * @brief Returns the `finished` property of `NSOperation`. - * @details A Boolean value indicating whether the operation has finished executing its task. The value of this property is 'YES' if the operation has finished its main task or 'NO' if it is executing that task or has not yet started it. When implementing a concurrent operation object, you must override the implementation of this property so that you can return the finished state of your operation. In your custom implementation, you must generate KVO notifications for the 'isFinished' key path whenever the finished state of your operation object changes. * @return The converted Objective-C result. */ bool is_finished() const; /** * @brief Returns the `name` property of `NSOperation`. - * @details The name of the operation. Assign a name to the operation object to help identify it during debugging. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSOperation`. - * @details The name of the operation. Assign a name to the operation object to help identify it during debugging. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; /** * @brief Returns the `qualityOfService` property of `NSOperation`. - * @details The relative amount of importance for granting system resources to the operation. Service levels affect the priority with which an operation object is given access to system resources such as CPU time, network resources, disk resources, and so on. Operations with a higher quality of service level are given greater priority over system resources so that they may perform their task more quickly. * @return The converted Objective-C result. */ QualityOfService quality_of_service() const; /** * @brief Sets the `qualityOfService` property of `NSOperation`. - * @details The relative amount of importance for granting system resources to the operation. Service levels affect the priority with which an operation object is given access to system resources such as CPU time, network resources, disk resources, and so on. Operations with a higher quality of service level are given greater priority over system resources so that they may perform their task more quickly. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_quality_of_service(QualityOfService value) const; /** * @brief Returns the `queuePriority` property of `NSOperation`. - * @details The execution priority of the operation in an operation queue. This property contains the relative priority of the operation. This value is used to influence the order in which operations are dequeued and executed. You should use priority values only as needed to classify the relative priority of non-dependent operations. Priority values should not be used to implement dependency management among different operation objects. If you need to establish dependencies between operations, use the ''addDependency:'' method instead. * @return The converted Objective-C result. */ OperationQueuePriority queue_priority() const; /** * @brief Sets the `queuePriority` property of `NSOperation`. - * @details The execution priority of the operation in an operation queue. This property contains the relative priority of the operation. This value is used to influence the order in which operations are dequeued and executed. You should use priority values only as needed to classify the relative priority of non-dependent operations. Priority values should not be used to implement dependency management among different operation objects. If you need to establish dependencies between operations, use the ''addDependency:'' method instead. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_queue_priority(OperationQueuePriority value) const; /** * @brief Returns the `ready` property of `NSOperation`. - * @details A Boolean value indicating whether the operation can be performed now. The readiness of operations is determined by their dependencies on other operations and potentially by custom conditions that you define. The 'NSOperation' class manages dependencies on other operations and reports the readiness of the receiver based on those dependencies. If you want to use custom conditions to define the readiness of your operation object, reimplement this property and return a value that accurately reflects the readiness of the receiver. If you do so, your custom implementation must get the default property value from 'super' and incorporate that readiness value into the new value of the property. In your custom implementation, you must generate KVO notifications for the 'isReady' key path whenever the ready state of your operation object changes. * @return The converted Objective-C result. */ bool is_ready() const; diff --git a/include/generated/operation_queue.h b/include/generated/operation_queue.h index 8a61fd0b..2938eee1 100644 --- a/include/generated/operation_queue.h +++ b/include/generated/operation_queue.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSOperationQueue` (Foundation). - * @details A queue that regulates the execution of operations. An operation queue invokes its queued ''Operation'' objects based on their priority and readiness. After you add an operation to a queue, it remains in the queue until the operation finishes its task. You can't directly remove an operation from a queue after you add it. > Note: > Operation queues retain operations until the operations finish, and queues themselves are retained until all operations are finished. Suspending an operation queue with operations that aren't finished can result in a memory leak. For more information about using operation queues, see the [Concurrency Programming Guide](https://developer.apple.com/library/archive/documentation/General/Conceptual/ConcurrencyProgrammingGuide/Introduction/Introduction.html\#//apple_ref/doc/uid/TP40008091). \#\#\# Determine the Execution Order An operation queue organizes and invokes its operations according to their readiness, priority level, and interoperation dependencies. If all of the queued operations have the same ''Operation/queuePriority'' and the ''Operation/isReady'' property returns \, the queue invokes them in the order you added them. Otherwise, the operation queue always invokes the operation with the highest priority relative to the other ready operations. However, don't rely on queue semantics to ensure a specific execution order of operations because changes in the readiness of an operation can change the resulting execution order. Interoperation dependencies provide an absolute execution order for operations, even if those operations are located in different operation queues. An operation object isn't ready to run until all of its dependent operations have finished running. For details on how to set priority levels and dependencies, see Managing Dependencies in ''Operation''. \#\#\# Respond to Operation Cancelation Finishing its task doesn't necessarily mean that the operation performed that task to completion; an operation can also be canceled. Canceling an operation object leaves the object in the queue but notifies the object that it should stop its task as quickly as possible. For currently executing operations, this means that the operation object's work code must check the cancellation state, stop what it is doing, and mark itself as finished. For operations that are queued but not yet executing, the queue must still call the operation object's ''Operation/start()'' method so that it can processes the cancellation event and mark itself as finished. > Note: > Canceling an operation causes the operation to ignore any dependencies it may have. This behavior makes it possible for the queue to invoke the operation's ''Operation/start()'' method as soon as possible. The ''Operation/start()'' method, in turn, moves the operation to the finished state so that it can be removed from the queue. For more information about operation cancellation, see \ in ''Operation''. \#\#\# Observe Operations Using Key-Value Observing The ''OperationQueue'' class is key-value coding (KVC) and key-value observing (KVO) compliant. You can observe these properties to control other parts of your application. To observe the properties, use the following key paths: - ''operations'' — Read-only - ''operationCount'' — Read-only - ''maxConcurrentOperationCount'' — Readable and writable - ''isSuspended'' — Readable and writable - ''name'' — Readable and writable Although you can attach observers to these properties, don't use Cocoa bindings to bind these properties to elements of your application's user interface. Code associated with your user interface typically must run only in your app's main thread. However, KVO notifications associated with an operation queue may occur in any thread. For more information about KVO and how to attach observers to an object, see the [Key-Value Observing Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html\#//apple_ref/doc/uid/10000177i). \#\#\# Plan for Thread Safety You can safely use a single ''OperationQueue'' object from multiple threads without creating additional locks to synchronize access to that object. Operation queues use the \ framework to initiate the execution of their operations. As a result, queues always invoke operations on a separate thread, regardless of whether the operation is synchronous or asynchronous. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -51,126 +50,107 @@ namespace cocoon explicit OperationQueue(Adopt adopt); /** * @brief Calls `-[NSOperationQueue addBarrierBlock:]`. - * @details Invokes a block when the queue finishes all enqueued operations, and prevents subsequent operations from starting until the block has completed. This method is similar to 'dispatch_barrier_async'. - Parameters: - barrier: The block to invoke after all currently enqueued operations have finished. Operations you add after the barrier block don't start until the block has completed. + * @details \@method addBarrierBlock: \@param barrier A block to execute \@discussion The 'addBarrierBlock:' method executes the block when the NSOperationQueue has finished all enqueued operations and prevents any subsequent operations to be executed until the barrier has been completed. This acts similarly to the 'dispatch_barrier_async' function. * @param barrier Argument converted to the Objective-C parameter of the same role. */ void add_barrier_block(std::function barrier) const; /** * @brief Calls `-[NSOperationQueue addOperation:]`. - * @details Adds the specified operation to the receiver. Once added, the specified operation remains in the queue until it finishes executing. An operation object can be in at most one operation queue at a time and this method throws an 'NSInvalidArgumentException' exception if the operation is already in another queue. Similarly, this method throws an 'NSInvalidArgumentException' exception if the operation is currently executing or has already finished executing. - Parameter op: The operation to be added to the queue. * @param op Argument converted to the Objective-C parameter of the same role. */ void add_operation(const Operation& op) const; /** * @brief Calls `-[NSOperationQueue addOperationWithBlock:]`. - * @details Wraps the specified block in an operation and adds it to the receiver. This method adds a single block to the receiver by first wrapping it in an operation object. You should not attempt to get a reference to the newly created operation object or determine its type information. - Parameter block: The block to execute from the operation. The block takes no parameters and has no return value. * @param block Argument converted to the Objective-C parameter of the same role. */ void add_operation_with_block(std::function block) const; /** * @brief Calls `-[NSOperationQueue addOperations:waitUntilFinished:]`. - * @details Adds the specified operations to the queue. An operation object can be in at most one operation queue at a time and cannot be added if it is currently executing or finished. This method throws an 'NSInvalidArgumentException' exception if any of those error conditions are true for any of the operations in the 'ops' parameter. - Parameters: - ops: The operations to be added to the queue. - wait: If 'YES', the current thread is blocked until all of the specified operations finish executing. If 'NO', the operations are added to the queue and control returns immediately to the caller. * @param ops Argument converted to the Objective-C parameter of the same role. * @param wait Argument converted to the Objective-C parameter of the same role. */ void add_operations(const std::vector& ops, bool wait) const; /** * @brief Calls `-[NSOperationQueue cancelAllOperations]`. - * @details Cancels all queued and executing operations. This method calls the 'cancel' method on all operations currently in the queue. Canceling the operations does not automatically remove them from the queue or stop those that are currently executing. For operations that are queued and waiting execution, the queue must still attempt to execute the operation before recognizing that it is canceled and moving it to the finished state. For operations that are already executing, the operation object itself must check for cancellation and stop what it is doing so that it can move to the finished state. */ void cancel_all_operations() const; /** * @brief Calls `-[NSOperationQueue waitUntilAllOperationsAreFinished]`. - * @details Blocks the current thread until all the receiver's queued and executing operations finish executing. When called, this method blocks the current thread and waits for the receiver's current and queued operations to finish executing. While the current thread is blocked, the receiver continues to launch already queued operations and monitor those that are executing. During this time, the current thread cannot add operations to the queue, but other threads may. Once all of the pending operations are finished, this method returns. If there are no operations in the queue, this method returns immediately. */ void wait_until_all_operations_are_finished() const; /** * @brief Returns the `currentQueue` property of `NSOperationQueue`. - * @details Returns the operation queue that launched the current operation. You can use this method from within a running operation object to get a reference to the operation queue that started it. Calling this method from outside the context of a running operation typically results in 'nil' being returned. * @return The converted Objective-C result. */ static OperationQueue current_queue(); /** * @brief Returns the `mainQueue` property of `NSOperationQueue`. - * @details Returns the operation queue associated with the main thread. The returned queue executes one operation at a time on the app's main thread. The execution of operations on the main thread is interleaved with the other tasks that must execute on the main thread, such as the servicing of events and the updating of an app's user interface. * @return The converted Objective-C result. */ static OperationQueue main_queue(); /** * @brief Returns the `maxConcurrentOperationCount` property of `NSOperationQueue`. - * @details The maximum number of queued operations that can run at the same time. The value in this property affects only the operations that the current queue has executing at the same time. Other operation queues can also execute their maximum number of operations in parallel. Reducing the number of concurrent operations does not affect any operations that are currently executing. Specifying the value 'NSOperationQueueDefaultMaxConcurrentOperationCount' (which is recommended) causes the system to set the maximum number of operations based on system conditions. The default value of this property is ''NSOperationQueueDefaultMaxConcurrentOperationCount''. * @return The converted Objective-C result. */ std::int64_t max_concurrent_operation_count() const; /** * @brief Sets the `maxConcurrentOperationCount` property of `NSOperationQueue`. - * @details The maximum number of queued operations that can run at the same time. The value in this property affects only the operations that the current queue has executing at the same time. Other operation queues can also execute their maximum number of operations in parallel. Reducing the number of concurrent operations does not affect any operations that are currently executing. Specifying the value 'NSOperationQueueDefaultMaxConcurrentOperationCount' (which is recommended) causes the system to set the maximum number of operations based on system conditions. The default value of this property is ''NSOperationQueueDefaultMaxConcurrentOperationCount''. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_max_concurrent_operation_count(std::int64_t value) const; /** * @brief Returns the `name` property of `NSOperationQueue`. - * @details The name of the operation queue. Names provide a way for you to identify your operation queues at run time. Tools may also use this name to provide additional context during debugging or analysis of your code. The default value of this property is a string containing the memory address of the operation queue. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSOperationQueue`. - * @details The name of the operation queue. Names provide a way for you to identify your operation queues at run time. Tools may also use this name to provide additional context during debugging or analysis of your code. The default value of this property is a string containing the memory address of the operation queue. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; /** * @brief Returns the `operationCount` property of `NSOperationQueue`. - * @details The number of operations currently in the queue. Because the number of operations in the queue changes as those operations finish executing, the value returned by this property reflects the instantaneous number of operations at the time the property was accessed. By the time you use the value, the actual number of operations may be different. As a result, do not use this value for object enumerations or other precise calculations. * @return The converted Objective-C result. */ std::uint64_t operation_count() const; /** * @brief Returns the `operations` property of `NSOperationQueue`. - * @details The operations currently in the queue. The array in this property contains zero or more 'NSOperation' objects in the order you added them to the queue. This order doesn't necessarily reflect the order in which the queue invokes those operations. * @return The converted Objective-C result. */ std::vector operations() const; /** * @brief Returns the `progress` property of `NSOperationQueue`. - * @details An object that represents the total progress of the operations executing in the queue. By default, ''NSOperationQueue'' doesn't report progress until the 'totalUnitCount' of the progress is set. When 'totalUnitCount' is set, the queue begins reporting progress. Each operation in the queue contributes one unit of completion to the overall progress of the queue for operations that are finished by the end of 'main'. Operations that override 'start' and don't invoke super don't contribute to the queue's progress. > Warning: > Be careful to avoid race conditions and backward progress when updating 'totalUnitCount'. Consider a queue with a progress that has a 'completedUnitCount' equal to '5' and a 'totalUnitCount' equal to '10', representing 50\% completion. If you add 90 more operations to the queue, the 'totalUnitCount' is now '100', and the progress completion reports 5\%. If the progress object is connected to a progress bar, the bar would visibly jump backward from 50\% to 5\%, which may not be desirable. To update 'totalUnitCount' in a thread-safe manner, use the 'addBarrierBlock:' method. This method ensures that the operation queue completes the operations in the queue, preventing an inadvertent backward jump in progress. + * @details \@property progress \@discussion The 'progress' property represents a total progress of the operations executed in the queue. By default NSOperationQueue does not report progress until the 'totalUnitCount' of the progress is set. When the 'totalUnitCount' property of the progress is set the queue then opts into participating in progress reporting. When enabled, each operation will contribute 1 unit of completion to the overall progress of the queue for operations that are finished by the end of main (operations that override start and do not invoke super will not contribute to progress). Special attention to race conditions should be made when updating the 'totalUnitCount' of the progress as well as care should be taken to avoid 'backwards progress'. For example; when a NSOperationQueue's progress is 5/10, representing 50\% completed, and there are 90 more operations about to be added and the 'totalUnitCount' that would then make the progress report as 5/100 which represents 5\%. In this example it would mean that any progress bar would jump from displaying 50\% back to 5\%, which might not be desirable. In the cases where the 'totalUnitCount' needs to be adjusted it is suggested to do this for thread-safety in a barrier by using the 'addBarrierBlock:' API. This ensures that no un-expected execution state occurs adjusting into a potentially backwards moving progress scenario. \@example NSOperationQueue queue = [[NSOperationQueue alloc] init]; queue.progress.totalUnitCount = 10; * @return The converted Objective-C result. */ Progress progress() const; /** * @brief Returns the `qualityOfService` property of `NSOperationQueue`. - * @details The default service level to apply to operations that the queue invokes. This property specifies the service level applied to operation objects added to the queue. If the operation object has an explicit service level set, that value is used instead. For queues you create yourself, the default value is 'NSOperationQualityOfServiceBackground'. For the queue returned by the 'mainQueue' method, the default value is 'NSOperationQualityOfServiceUserInteractive' and cannot be changed. * @return The converted Objective-C result. */ QualityOfService quality_of_service() const; /** * @brief Sets the `qualityOfService` property of `NSOperationQueue`. - * @details The default service level to apply to operations that the queue invokes. This property specifies the service level applied to operation objects added to the queue. If the operation object has an explicit service level set, that value is used instead. For queues you create yourself, the default value is 'NSOperationQualityOfServiceBackground'. For the queue returned by the 'mainQueue' method, the default value is 'NSOperationQualityOfServiceUserInteractive' and cannot be changed. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_quality_of_service(QualityOfService value) const; /** * @brief Returns the `suspended` property of `NSOperationQueue`. - * @details A Boolean value indicating whether the queue is actively scheduling operations for execution. When the value of this property is 'NO', the queue actively starts operations that are in the queue and ready to execute. Setting this property to 'YES' prevents the queue from starting any queued operations, but already executing operations continue to execute. You may continue to add operations to a queue that is suspended but those operations are not scheduled for execution until you change this property to 'NO'. Operations are removed from the queue only when they finish executing. However, in order to finish executing, an operation must first be started. Because a suspended queue does not start any new operations, it does not remove any operations (including cancelled operations) that are currently queued and not executing. The default value of this property is 'NO'. * @return The converted Objective-C result. */ bool is_suspended() const; /** * @brief Sets the `suspended` property of `NSOperationQueue`. - * @details A Boolean value indicating whether the queue is actively scheduling operations for execution. When the value of this property is 'NO', the queue actively starts operations that are in the queue and ready to execute. Setting this property to 'YES' prevents the queue from starting any queued operations, but already executing operations continue to execute. You may continue to add operations to a queue that is suspended but those operations are not scheduled for execution until you change this property to 'NO'. Operations are removed from the queue only when they finish executing. However, in order to finish executing, an operation must first be started. Because a suspended queue does not start any new operations, it does not remove any operations (including cancelled operations) that are currently queued and not executing. The default value of this property is 'NO'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_suspended(bool value) const; /** * @brief Returns the `underlyingQueue` property of `NSOperationQueue`. - * @details The dispatch queue that the operation queue uses to invoke operations. The default value of this property is 'nil'. You can set the value of this property to an existing dispatch queue to have enqueued operations interspersed with blocks submitted to that dispatch queue. The value of this property should only be set if there are no operations in the queue; setting the value of this property when 'operationCount' is not equal to '0' raises an 'NSInvalidArgumentException'. The value of this property must not be the value returned by 'dispatch_get_main_queue'. The quality-of-service level set for the underlying dispatch queue overrides any value set for the operation queue's 'qualityOfService' property. * @return The converted Objective-C result. */ Object underlying_queue() const; /** * @brief Sets the `underlyingQueue` property of `NSOperationQueue`. - * @details The dispatch queue that the operation queue uses to invoke operations. The default value of this property is 'nil'. You can set the value of this property to an existing dispatch queue to have enqueued operations interspersed with blocks submitted to that dispatch queue. The value of this property should only be set if there are no operations in the queue; setting the value of this property when 'operationCount' is not equal to '0' raises an 'NSInvalidArgumentException'. The value of this property must not be the value returned by 'dispatch_get_main_queue'. The quality-of-service level set for the underlying dispatch queue overrides any value set for the operation queue's 'qualityOfService' property. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_underlying_queue(const Object& value) const; diff --git a/include/generated/ordered_collection_change_base.h b/include/generated/ordered_collection_change_base.h index d77df83e..508d1023 100644 --- a/include/generated/ordered_collection_change_base.h +++ b/include/generated/ordered_collection_change_base.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSOrderedCollectionChange` (Foundation). - * @details An object that represents an indexed change within an ordered collection. An ordered collection change represents changes by adding, removing, or moving objects within an ordered collection. Changes with an associated index indicate a move within the collection. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref OrderedCollectionChange to supply ObjectType. * @@ -36,7 +35,6 @@ namespace cocoon explicit OrderedCollectionChangeBase(Adopt adopt); /** * @brief Calls `+[NSOrderedCollectionChange changeWithObject:type:index:]`. - * @details Creates a change object that represents inserting or removing an object from an ordered collection at a specific index. - Parameter anObject: An object to be removed or inserted by the change. - Parameter type: The type of change. - Parameter index: The index location within an ordered collection where the change applies. * @param an_object Argument converted to the Objective-C parameter of the same role. * @param type Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. @@ -45,7 +43,6 @@ namespace cocoon static OrderedCollectionChangeBase change_with_object(const Object& an_object, CollectionChangeType type, std::uint64_t index); /** * @brief Calls `+[NSOrderedCollectionChange changeWithObject:type:index:associatedIndex:]`. - * @details Creates a change object that represents inserting or removing an object from an ordered collection at a specific index, matched with an associated location that infers a move within the collection. - Parameter anObject: An object to be removed or inserted by the change. - Parameter type: The type of change. - Parameter index: The index location within an ordered collection where the change applies. - Parameter associatedIndex: The index of the change's counterpart of the opposite type in the diff. * @param an_object Argument converted to the Objective-C parameter of the same role. * @param type Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. @@ -55,25 +52,21 @@ namespace cocoon static OrderedCollectionChangeBase change_with_object(const Object& an_object, CollectionChangeType type, std::uint64_t index, std::uint64_t associated_index); /** * @brief Returns the `associatedIndex` property of `NSOrderedCollectionChange`. - * @details When this property is set to a value other than 'NSNotFound', the receiver is one half of a move, and this value is the index of the change's counterpart of the opposite type in the diff. Pairs of changes with opposite types that refer to each other represent the index location of their counterpart with the 'associatedIndex' property. A move pair can have a different 'object' in its removal and insertion changes, which can imply that the change represents moving and changing or replacing an element. > Note: > Don't ignore a move when the indexes of its changes are the same. The calculated difference may legitimately produce a diff where a change removes the object at one index and the object at another index moves to the same index. Ignoring the move produces an incorrect result. * @return The converted Objective-C result. */ std::uint64_t associated_index() const; /** * @brief Returns the `changeType` property of `NSOrderedCollectionChange`. - * @details The type of change. * @return The converted Objective-C result. */ CollectionChangeType change_type() const; /** * @brief Returns the `index` property of `NSOrderedCollectionChange`. - * @details The index location of the change. For removals, the index of the object in the original state. For insertions, the index of the object in the final state. * @return The converted Objective-C result. */ std::uint64_t index() const; /** * @brief Returns the `object` property of `NSOrderedCollectionChange`. - * @details An object the change inserts or removes. * @return The converted Objective-C result. */ Object object() const; diff --git a/include/generated/ordered_collection_difference_base.h b/include/generated/ordered_collection_difference_base.h index e22668ca..d2924756 100644 --- a/include/generated/ordered_collection_difference_base.h +++ b/include/generated/ordered_collection_difference_base.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSOrderedCollectionDifference` (Foundation). - * @details An object representing the difference between two ordered collections. Use ''NSArray/differenceFromArray:'' or one of its variations to get an instance of ''NSOrderedCollectionDifference'', which represents the difference between two ordered collections. For example, the following sample compares two arrays of strings to create a difference that represents the changes: '''objc NSArray original = \@[\@"Red", \@"Green", \@"Blue"]; NSArray modified = \@[\@"Red", \@"Blue", \@"Green"]; NSOrderedCollectionDifference diff = [original differenceFromArray:modified]; // diff.hasChanges == TRUE // diff.insertions.count == 1 // diff.removals.count == 1 ''' * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Use the typed template @ref OrderedCollectionDifference to supply ObjectType. * @@ -49,32 +48,27 @@ namespace cocoon explicit OrderedCollectionDifferenceBase(Adopt adopt); /** * @brief Calls `-[NSOrderedCollectionDifference differenceByTransformingChangesWithBlock:]`. - * @details Create a new ordered collection difference by mapping over this difference's members, processing the change objects with the block provided. - Parameter block: A block that receives an ordered collection change and returns an updated change. - Returns: A new ordered collection difference. * @param block Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ OrderedCollectionDifferenceBase difference_by_transforming_changes_with_block(std::function block) const; /** * @brief Calls `-[NSOrderedCollectionDifference inverseDifference]`. - * @details Returns a difference that is the inverse of the receiver. Applying a difference to an ordered collection and then applying the inverse difference results in the original ordered collection. To revert a chronological sequence of diffs, apply their inverses in reverse order. * @return The converted Objective-C result. */ OrderedCollectionDifferenceBase inverse_difference() const; /** * @brief Returns the `hasChanges` property of `NSOrderedCollectionDifference`. - * @details A Boolean value that indicates if the difference has changes. * @return The converted Objective-C result. */ bool has_changes() const; /** * @brief Returns the `insertions` property of `NSOrderedCollectionDifference`. - * @details A collection of insertion change objects. * @return The converted Objective-C result. */ std::vector insertions() const; /** * @brief Returns the `removals` property of `NSOrderedCollectionDifference`. - * @details A collection of removal change objects. * @return The converted Objective-C result. */ std::vector removals() const; diff --git a/include/generated/orthography.h b/include/generated/orthography.h index f564e671..554881cc 100644 --- a/include/generated/orthography.h +++ b/include/generated/orthography.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSOrthography` (Foundation). - * @details A description of the linguistic content of natural language text, typically used for spelling and grammar checking. Use ''NSOrthography'' objects to describe the linguistic content of a piece of text, including which scripts the text contains, a dominant language (and possibly other languages) for each script, and a dominant script and language for the text as a whole. Scripts are uniformly described by four-letter ISO 15924 script codes, such as '"Latn"', '"Grek"', and '"Cyrl"'. The supertags '"Jpan"' and '"Kore"' are typically used for Japanese and Korean text, and '"Hans"' and '"Hant"' are typically used for Chinese text. The tag '"Zyyy"' is used if a specific script cannot be identified. See [Internationalization and Localization Guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/Introduction/Introduction.html\#//apple_ref/doc/uid/10000171i) for more information. Languages are uniformly described by BCP-47 tags (preferably in canonical form). The tag '"und"' is used if a specific language cannot be determined. You typically work with orthography objects returned from methods and properties for classes like ''NSLinguisticTagger'' and \. \#\#\# Subclassing Notes Subclasses must override the ''dominantScript'' and ''languageMap'' properties. These properties are set using ''init(dominantScript:languageMap:)'' or ''orthographyWithDominantScript:languageMap:'' in Objective-C. + * @details NSOrthography is a class used to describe the linguistic content of a piece of text, especially for the purposes of spelling and grammar checking. It describes (a) which scripts the text contains, (b) a dominant language and possibly other languages for each of these scripts, and (c) a dominant script and language for the text as a whole. Scripts are uniformly described by standard four-letter tags (Latn, Grek, Cyrl, etc.) with the supertags Jpan and Kore typically used for Japanese and Korean text, Hans and Hant for Chinese text; the tag Zyyy is used if a specific script cannot be identified. Languages are uniformly described by BCP-47 tags, preferably in canonical form; the tag und is used if a specific language cannot be determined. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -43,52 +43,47 @@ namespace cocoon explicit Orthography(Adopt adopt); /** * @brief Calls `+[NSOrthography defaultOrthographyForLanguage:]`. - * @details Creates and returns an orthography object with the default language map for the specified language. This method automatically determines the script for the specified language. - Parameter language: A BCP-47 tag identifying the language. * @param language Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Orthography default_orthography_for_language(const std::string& language); /** * @brief Calls `-[NSOrthography dominantLanguageForScript:]`. - * @details Returns the dominant language for the specified script. - Parameter script: The specified script. * @param script Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string dominant_language_for_script(const std::string& script) const; /** * @brief Calls `-[NSOrthography languagesForScript:]`. - * @details Returns the list of languages for the specified script. - Parameter script: The specified script. + * @details languagesForScript: returns the list of languages for the specified script, and dominantLanguageForScript: returns the first item on that list. * @param script Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector languages_for_script(const std::string& script) const; /** * @brief Returns the `allLanguages` property of `NSOrthography`. - * @details The languages appearing in values of the language map. * @return The converted Objective-C result. */ std::vector all_languages() const; /** * @brief Returns the `allScripts` property of `NSOrthography`. - * @details The scripts appearing as keys in the language map. * @return The converted Objective-C result. */ std::vector all_scripts() const; /** * @brief Returns the `dominantLanguage` property of `NSOrthography`. - * @details The first language in the list of languages for the dominant script. + * @details The dominantLanguage is the first in the list of languages for the dominant script, allScripts includes the dominant script and all others appearing as keys in the language map, and allLanguages includes all languages appearing in the values of the language map. * @return The converted Objective-C result. */ std::string dominant_language() const; /** * @brief Returns the `dominantScript` property of `NSOrthography`. - * @details The dominant script for the text. The value of this property is an ISO 15924 script code, such as '"Latn"' or '"Cyrl"', that identifies the dominant script. + * @details These are the primitive properties which a subclass must implement. The dominantScript should be a script tag (such as Latn, Cyrl, and so forth) and the languageMap should be a dictionary whose keys are script tags and whose values are arrays of language tags (such as en, fr, de, and so forth). * @return The converted Objective-C result. */ std::string dominant_script() const; /** * @brief Returns the `languageMap` property of `NSOrthography`. - * @details A dictionary that maps script tags to arrays of language tags. The dictionary's keys are ISO 15924 script codes (such as '"Latn"' or '"Cyrl"') and its values are arrays of BCP-47 language tags (such as '"en"', '"fr"', or '"de"'). * @return The converted Objective-C result. */ std::map> language_map() const; diff --git a/include/generated/output_stream.h b/include/generated/output_stream.h index 3428b1ec..ad0c1d70 100644 --- a/include/generated/output_stream.h +++ b/include/generated/output_stream.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSOutputStream` (Foundation). - * @details A stream that provides write-only stream functionality. ''OutputStream'' is "toll-free bridged" with its Core Foundation counterpart, \. For more information on toll-free bridging, see [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2). \#\#\# Subclassing Notes 'NSOutputStream' is a concrete subclass of 'NSStream' that lets you write data to a stream. Although 'NSOutputStream' is probably sufficient for most situations requiring this capability, you can create a subclass of 'NSOutputStream' if you want more specialized behavior (for example, you want to record statistics on the data in a stream). \#\#\#\# Methods to Override To create a subclass of 'NSOutputStream' you may have to implement initializers for the type of stream data supported and suitably reimplement existing initializers. You must also provide complete implementations of the following methods: - ''write(:maxLength:)'' From the current write pointer, take up to the number of bytes specified in the 'maxLength:' parameter from the client-supplied buffer (first parameter) and put them onto the stream. The buffer must be of the size specified by the second parameter. To prepare for the next operation, offset the write pointer by the number of bytes written. Return a signed integer based on the outcome of the current operation: - If the write operation is successful, return the actual number of bytes put onto the stream. - If the stream is of a fixed length and has reached its capacity, return '0'. - If there was an error writing to the stream, return '-1'. - ''hasSpaceAvailable'' Return \ if the stream can currently accept more data, \ if it cannot. If you want to be semantically compatible with 'NSOutputStream', return \ if a write must be attempted to determine if space is available. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Stream. * @@ -49,7 +48,6 @@ namespace cocoon explicit OutputStream(Adopt adopt); /** * @brief Calls `+[NSOutputStream outputStreamToBuffer:capacity:]`. - * @details Creates and returns an initialized output stream that can write to a provided buffer. The stream must be opened before it can be used. When the number of bytes written to 'buffer' has reached 'capacity', the stream's 'streamStatus' will return 'NSStreamStatusAtEnd'. - Parameters: - buffer: The buffer the output stream will write to. - capacity: The size of the buffer in bytes. - Returns: An initialized output stream that can write to 'buffer'. * @param buffer Argument converted to the Objective-C parameter of the same role. * @param capacity Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -57,7 +55,6 @@ namespace cocoon static OutputStream output_stream_to_buffer(std::uint8_t* buffer, std::uint64_t capacity); /** * @brief Calls `+[NSOutputStream outputStreamToFileAtPath:append:]`. - * @details Creates and returns an initialized output stream for writing to a specified file. The stream must be opened before it can be used. - Parameters: - path: The path to the file the output stream will write to. - shouldAppend: 'YES' if newly written data should be appended to any existing file contents, otherwise 'NO'. - Returns: An initialized output stream that can write to 'path'. * @param path Argument converted to the Objective-C parameter of the same role. * @param should_append Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -65,13 +62,11 @@ namespace cocoon static OutputStream output_stream_to_file_at_path(const std::string& path, bool should_append); /** * @brief Calls `+[NSOutputStream outputStreamToMemory]`. - * @details Creates and returns an initialized output stream that will write stream data to memory. The stream must be opened before it can be used. You retrieve the contents of the memory stream by sending the message 'propertyForKey:' to the receiver with an argument of 'NSStreamDataWrittenToMemoryStreamKey'. * @return The converted Objective-C result. */ static OutputStream output_stream_to_memory(); /** * @brief Calls `-[NSOutputStream write:maxLength:]`. - * @details Writes the contents of a provided data buffer to the receiver. - Parameters: - buffer: The data to write. - len: The length of the data buffer, in bytes. The behavior of this method is undefined if you pass a negative or zero number. - Returns: A positive number indicates the number of bytes written; '0' indicates that a fixed-length stream has reached its capacity; '-1' means that the operation failed (more information about the error can be obtained with 'streamError'). * @param buffer Argument converted to the Objective-C parameter of the same role. * @param len Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -79,7 +74,6 @@ namespace cocoon std::int64_t write(const std::uint8_t* buffer, std::uint64_t len) const; /** * @brief Returns the `hasSpaceAvailable` property of `NSOutputStream`. - * @details A Boolean value that indicates whether the receiver can be written to. 'YES' if the stream can be written to or if a write must be attempted in order to determine if space is available, 'NO' otherwise. * @return The converted Objective-C result. */ bool has_space_available() const; diff --git a/include/generated/pan_gesture_recognizer.h b/include/generated/pan_gesture_recognizer.h index d40ad3b8..dcee4cd6 100644 --- a/include/generated/pan_gesture_recognizer.h +++ b/include/generated/pan_gesture_recognizer.h @@ -29,10 +29,8 @@ namespace cocoon * cocoon::PanGestureRecognizer pan_gesture_recognizer{}; * pan_gesture_recognizer.set_button_mask(1); * auto button_mask = pan_gesture_recognizer.button_mask(); - * pan_gesture_recognizer.set_maximum_number_of_touches(1); - * auto maximum_number_of_touches = pan_gesture_recognizer.maximum_number_of_touches(); - * pan_gesture_recognizer.set_minimum_number_of_touches(1); - * auto minimum_number_of_touches = pan_gesture_recognizer.minimum_number_of_touches(); + * pan_gesture_recognizer.set_number_of_touches_required(1); + * auto number_of_touches_required = pan_gesture_recognizer.number_of_touches_required(); * pan_gesture_recognizer.set_translation({0, 0}, cocoon::View()); * pan_gesture_recognizer.translation_in_view(cocoon::View()); * pan_gesture_recognizer.velocity_in_view(cocoon::View()); @@ -80,42 +78,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_button_mask(std::uint64_t value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `maximumNumberOfTouches` property of `NSPanGestureRecognizer`. - * @details The maximum number of touches allowed to recognize this gesture Set this property to 0 to require exactly 'minimumNumberOfTouches' touches to recognize the gesture. Defaults to 'NSIntegerMax'. - * @return The converted Objective-C result. - */ - std::int64_t maximum_number_of_touches() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `maximumNumberOfTouches` property of `NSPanGestureRecognizer`. - * @details The maximum number of touches allowed to recognize this gesture Set this property to 0 to require exactly 'minimumNumberOfTouches' touches to recognize the gesture. Defaults to 'NSIntegerMax'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_maximum_number_of_touches(std::int64_t value) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `minimumNumberOfTouches` property of `NSPanGestureRecognizer`. - * @details The minimum number of touches needed to recognize this gesture Defaults to 1. - * @return The converted Objective-C result. - */ - std::int64_t minimum_number_of_touches() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `minimumNumberOfTouches` property of `NSPanGestureRecognizer`. - * @details The minimum number of touches needed to recognize this gesture Defaults to 1. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_minimum_number_of_touches(std::int64_t value) const; -#endif - /** * @brief Returns the `numberOfTouchesRequired` property of `NSPanGestureRecognizer`. * @details Number of touches required to recognize the gesture when used in NSTouchBar diff --git a/include/generated/paragraph_style.h b/include/generated/paragraph_style.h index 397e1b38..6ecdcc86 100644 --- a/include/generated/paragraph_style.h +++ b/include/generated/paragraph_style.h @@ -8,7 +8,6 @@ namespace cocoon { - class TextBlock; class TextList; class TextTab; @@ -35,146 +34,102 @@ namespace cocoon explicit ParagraphStyle(Adopt adopt); /** * @brief Calls `+[NSParagraphStyle defaultWritingDirectionForLanguage:]`. - * @details Returns the default writing direction for the specified language. - Parameters: - languageName: The language specified in ISO language region format. Can be 'nil' to return a default writing direction derived from the user's defaults database. - Returns: The default writing direction. * @param language_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static WritingDirection default_writing_direction_for_language(const std::string& language_name); - /** - * @brief Returns the `alignment` property of `NSParagraphStyle`. - * @details The text alignment of the paragraph. - * @return The converted Objective-C result. - */ - TextAlignment alignment() const; /** * @brief Returns the `allowsDefaultTighteningForTruncation` property of `NSParagraphStyle`. - * @details A Boolean value that indicates whether the system tightens character spacing before truncating text. When this property is \, the system tries to reduce the space between characters before truncating characters. The system performs this tightening in cases where the text wouldn't otherwise fit in the available space. The maximum amount of tightening performed by the system is dependent on the font, line width, and other factors. The default value of this property is \. * @return The converted Objective-C result. */ bool allows_default_tightening_for_truncation() const; /** * @brief Returns the `baseWritingDirection` property of `NSParagraphStyle`. - * @details The base writing direction for the paragraph. If the value of this property is ''NSWritingDirection/natural'', the consumer of the value must resolve the writing direction based on the paragraph contents using the Unicode Bidi Algorithm. * @return The converted Objective-C result. */ WritingDirection base_writing_direction() const; /** * @brief Returns the `defaultParagraphStyle` property of `NSParagraphStyle`. - * @details The default paragraph style. The default paragraph style has the following default values: | Subattribute | Default | |---|---| | Alignment | 'NSNaturalTextAlignment' | | Tab stops | 12 left-aligned tabs, spaced by '28.0' points | | Line break mode | 'NSLineBreakByWordWrapping' | | All others | '0.0' | See individual method descriptions for explanations of each subattribute. * @return The converted Objective-C result. */ static ParagraphStyle default_paragraph_style(); /** * @brief Returns the `defaultTabInterval` property of `NSParagraphStyle`. - * @details The documentwide default tab interval. This property represents the default tab interval in points. Tabs after the last specified in ''NSParagraphStyle/tabStops'' are placed at integer multiples of this distance (if positive). Default value is '0.0'. * @return The converted Objective-C result. */ double default_tab_interval() const; /** * @brief Returns the `firstLineHeadIndent` property of `NSParagraphStyle`. - * @details The indentation of the first line of the paragraph. This property contains the distance (in points) from the leading margin of a text container to the beginning of the paragraph's first line. This value is always nonnegative. * @return The converted Objective-C result. */ double first_line_head_indent() const; /** * @brief Returns the `headIndent` property of `NSParagraphStyle`. - * @details The indentation of the paragraph's lines other than the first. This property contains the distance (in points) from the leading margin of a text container to the beginning of lines other than the first. This value is always nonnegative. * @return The converted Objective-C result. */ double head_indent() const; - /** - * @brief Returns the `headerLevel` property of `NSParagraphStyle`. - * @details The paragraph's header level for HTML generation. Should be set to '0' (the default value) if the paragraph is not a header, or from 1 through 6 if the paragraph is to be treated as a header. - * @return The converted Objective-C result. - */ - std::int64_t header_level() const; /** * @brief Returns the `hyphenationFactor` property of `NSParagraphStyle`. - * @details The paragraph's threshold for hyphenation. The system attempts hyphenation when the ratio of the text width (as broken without hyphenation) to the width of the line fragment is less than the hyphenation factor. When the paragraph's hyphenation factor is '0.0', the system uses the text layout manager's hyphenation factor instead. The system disables hyphenation when both are '0.0'. This property detects the user-selected language by examining the first item in \. \#\# See Also - \ * @return The converted Objective-C result. */ float hyphenation_factor() const; /** * @brief Returns the `lineBreakMode` property of `NSParagraphStyle`. - * @details The mode for breaking lines in the paragraph that don't fit within a container. This property controls how the text system lays out lines that don't fit in its container, such as by truncating with an ellipsis (…) or clipping the text. This is different from ''NSParagraphStyle/LineBreakStrategy'', which controls where the system places line breaks in a paragraph. * @return The converted Objective-C result. */ LineBreakMode line_break_mode() const; /** * @brief Returns the `lineBreakStrategy` property of `NSParagraphStyle`. - * @details The strategy for breaking lines while laying out paragraphs. Line-break strategies are collections of options the system uses to determine where to break lines in a paragraph. This is different from ''NSParagraphStyle/lineBreakMode'', which controls how to lay out lines of text that don't fit in a container. The system ignores this property if the paragraph style's ''NSParagraphStyle/lineBreakMode'' property specifies a mode that doesn't support multiple lines, such as ''NSLineBreakMode/byClipping''. The default value is ''NSLineBreakStrategy/NSLineBreakStrategyNone''. * @return The converted Objective-C result. */ LineBreakStrategy line_break_strategy() const; /** * @brief Returns the `lineHeightMultiple` property of `NSParagraphStyle`. - * @details The line height multiple. The framework multiplies the natural line height of the receiver by this factor (if positive), and constrains the resulting value by the minimum and maximum line height. The default value of this property is '0.0'. * @return The converted Objective-C result. */ double line_height_multiple() const; /** * @brief Returns the `lineSpacing` property of `NSParagraphStyle`. - * @details The distance in points between the bottom of one line fragment and the top of the next. This value is always nonnegative. The text layout manager uses this value in the line fragment height. * @return The converted Objective-C result. */ double line_spacing() const; /** * @brief Returns the `maximumLineHeight` property of `NSParagraphStyle`. - * @details The paragraph's maximum line height. This property contains the maximum height in points that any line in the receiver occupies, regardless of the font size or size of any attached graphic. This value is always nonnegative. The default value is '0'. Glyphs and graphics exceeding this height overlap neighboring lines; however, a maximum height of '0' implies no line height limit. Although this limit applies to the line itself, line spacing adds extra space between adjacent lines. * @return The converted Objective-C result. */ double maximum_line_height() const; /** * @brief Returns the `minimumLineHeight` property of `NSParagraphStyle`. - * @details The paragraph's minimum line height. This property contains the minimum height in points that any line in the receiver occupies, regardless of the font size or size of any attached graphic. This value is always nonnegative. * @return The converted Objective-C result. */ double minimum_line_height() const; /** * @brief Returns the `paragraphSpacing` property of `NSParagraphStyle`. - * @details Distance between the bottom of this paragraph and top of next. This property contains the space (measured in points) between paragraphs. This value is always nonnegative. The framework determines the space between paragraphs by adding the previous paragraph's 'paragraphSpacing' and the current paragraph's ''NSParagraphStyle/paragraphSpacingBefore''. * @return The converted Objective-C result. */ double paragraph_spacing() const; /** * @brief Returns the `paragraphSpacingBefore` property of `NSParagraphStyle`. - * @details The distance between the paragraph's top and the beginning of its text content. This property contains the space (measured in points) between the current and previous paragraphs. The default value of this property is '0.0'. * @return The converted Objective-C result. */ double paragraph_spacing_before() const; /** * @brief Returns the `tabStops` property of `NSParagraphStyle`. - * @details The text tab objects that represent the paragraph's tab stops. The ''NSTextTab'' objects, sorted by location, define the tab stops for the paragraph style. The default value is an array of 12 left-aligned tabs at 28-point intervals. * @return The converted Objective-C result. */ std::vector tab_stops() const; /** * @brief Returns the `tailIndent` property of `NSParagraphStyle`. - * @details The trailing indentation of the paragraph. If positive, this value is the distance from the leading margin (for example, the left margin in left-to-right text). If '0' or negative, it's the distance from the trailing margin. For example, a paragraph style designed to fit exactly in a two-inch wide container has a head indent of '0.0' and a tail indent of '0.0'. One designed to fit with a quarter-inch margin has a head indent of '0.25' and a tail indent of '–0.25'. * @return The converted Objective-C result. */ double tail_indent() const; - /** - * @brief Returns the `textBlocks` property of `NSParagraphStyle`. - * @details The text blocks that contain the paragraph, nested from outermost to innermost. - * @return The converted Objective-C result. - */ - std::vector text_blocks() const; /** * @brief Returns the `textLists` property of `NSParagraphStyle`. - * @details The text lists that contain the paragraph, nested from outermost to innermost. * @return The converted Objective-C result. */ std::vector text_lists() const; - /** - * @brief Returns the `tighteningFactorForTruncation` property of `NSParagraphStyle`. - * @details The threshold for using tightening as an alternative to truncation. When the line break mode specifies truncation, the text system will attempt to tighten inter-character spacing as an alternative to truncation, provided that the ratio of the text width to the line fragment width does not exceed '1.0 + tighteningFactorForTruncation'. Otherwise the text will be truncated at a location determined by the line break mode. The default value is '0.0' for apps linked against 10.11 and later SDK. This property is ignored when ''allowsDefaultTighteningForTruncation'' is 'true'. Explicitly setting this property to '0.0' has a side effect of also setting ''allowsDefaultTighteningForTruncation'' to 'false'. - * @return The converted Objective-C result. - */ - float tightening_factor_for_truncation() const; /** * @brief Returns the `usesDefaultHyphenation` property of `NSParagraphStyle`. - * @details A Boolean value that indicates whether the paragraph style uses the system hyphenation settings. The system determines the exact hyphenation logic dynamically by examining the layout context such as language, platform, etc. When 'true', it affects the return value from ''hyphenationFactor'' when the property is set to '0.0'. * @return The converted Objective-C result. */ bool uses_default_hyphenation() const; diff --git a/include/generated/person_name_components.h b/include/generated/person_name_components.h index 3ad9bfd0..155e2a9d 100644 --- a/include/generated/person_name_components.h +++ b/include/generated/person_name_components.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSPersonNameComponents` (Foundation). - * @details An object that manages the separate parts of a person's name to allow locale-aware formatting. You can use this type in Swift when you need reference semantics or other Foundation-specific behavior. An 'NSPersonNameComponents' object encapsulates the components of a person's name in an extendable, object-oriented manner. It is used to specify a person's name by providing the components comprising a full name: given name, middle name, family name, prefix, suffix, nickname, and phonetic representation. 'NSPersonNameComponents' objects can be used by an instance of ''PersonNameComponentsFormatter'' to create string representations suitable for display in the current locale. > Important: > The Swift overlay to the Foundation framework provides the ''PersonNameComponents'' structure, which bridges to the ''NSPersonNameComponents'' class. For more information about value types, see \. \#\#\# Working with Names It is important to understand that names are disjoint from a person's identity. An individual may, at any time, have zero, one, or many names. Names cannot be used as a determination of a person's identity, because two names may correspond to the same individual, and two people may have the same name. Nor can names be used as a determination of a person's relation to others, because an individual may have a different family name than their relatives, and two individuals may have the same family name, but not be related. Many locales and cultures have rules about what kinds of names are allowed and how they are structured. An 'NSPersonNameComponents' object does not impose any restrictions about which combinations of properties may have values or what those values may be. > Note: > 'NSPersonNameComponents' represents only the components of a name. To represent contact information, such as postal addresses or phone numbers, in addition to a personal name, use \ or \ instead. \#\#\# Name Components An 'NSPersonNameComponents' object encodes the following components of a personal name, which are described in detail below. - Given Name (''givenName'') - Middle Name (''middleName'') - Family Name (''familyName'') - Prefix (''namePrefix'') - Suffix (''nameSuffix'') - Nickname (''nickname'') - Phonetic Representation (''phoneticRepresentation'') \#\#\#\# Given Name A given name is bestowed upon an individual to differentiate them from other members of a group that share a family name. In some locales, this is also known as a "first name" or "forename." \#\#\#\#\# Multiple Given Names Names may consist of multiple given names. For example, the Spanish name "María Rosalía Rita de Castro" consists of the given names "María," "Rosalía," and "Rita." When modeling a name containing multiple given names with an 'NSPersonNameComponents' object, concatenate them using a locale-appropriate delimiter and set the result as the 'givenName' property value. If one of the given names is more commonly used in informal settings, such as "Rosalía" for "Rosalía de Castro," you can set that as the 'nickname' property value. \#\#\#\# Middle Name A middle name is a secondary given name bestowed upon an individual to differentiate them from others that have the same given name. \#\#\#\#\# Multiple Middle Names and Middle Initials Names can consist of one or more middle names in addition to a given name and/or family name. A middle name may appear only in certain styles, depending on the user localization preferences. A middle name may consist only of an initial, such as the American name "Salmon P. Chase." When modeling a name containing a middle initial, set the initial and locale-appropriate punctuation as the 'middleName' property value. Although many English-speaking locales commonly abbreviate middle names with middle initials, don't attempt to abbreviate a provided middle name yourself. Sometimes, a middle name is preferred to a given name for common use. In that case, set the 'middleName' property value as the nickname property value instead. When modeling a name containing multiple middle names with an 'NSPersonNameComponents' object, concatenate them using a locale-appropriate delimiter and set the result as the 'middleName' property value. \#\#\#\# Family Name A family name is a name bestowed upon an individual to denote membership in a group or family. \#\#\#\#\# Prepositional Particles Some family names consist of a prepositional phrase to denote nobility or regional ancestry, such as the Dutch name "Joost van den Vondel," which contains the prepositional phrase "van den." When modeling a name containing such a family name with an 'NSPersonNameComponents' object, include any prepositional particles as part of the 'familyName' property value. \#\#\#\#\# Composite Names Some family names consist of matronymic, patronymic, or other ancestral names. For example, the Chilean name "Manuel Xavier Rodríguez Erdoíza" consists of the paternal name "Rodríguez" and the maternal name "Erdoíza." The usage and order of composite name components vary across different locales and cultures. When modeling a name containing multiple family names with an 'NSPersonNameComponents' object, use the entire composite family name as the 'familyName' property value. \#\#\#\#\# Generational Name It is traditional in some locales, particularly in China, for relatives born in the same generation to have a common generational name. For example, the Chinese name "郑秋媛 (Zheng Qiuyuan)" consists of the family name "郑 (Zheng)" and the given name "秋媛 (Qiuyuan)." The generational name "秋 (Qiu)" might be shared between the names of siblings or cousins, for instance, "郑秋德 (Zheng Qiude)." When modeling a name consisting of a generational name with 'NSPersonNameComponents', you should use the combined generational and given name values as the 'givenName' property value. Some names incorporate generational suffixes, such as "Jr.," "Sr.," or a roman numeral (I, II, III, IV, etc.) to distinguish between family members that have the same name. For example, the Samoan name "Malietoa Tanumafili II" contains the generational suffix "II" to denote the second generation. When modeling a name consisting of a generational suffix with 'NSPersonNameComponents', use it as the 'nameSuffix' property value. \#\#\#\#\# Mononyms Some individuals are commonly, legally, and/or historically identified by a single name. For example, the Lithuanian names "Vydūnas," "Žemaitė," and "Maironis." When modeling a mononymous name with 'NSPersonNameComponents', set the name as the 'familyName' property value. \#\#\#\# Prefix and Suffix A name prefix is the portion of a name's full form of address that precedes the name itself. A name suffix is the portion of a name's full form of address that follows the name itself. Depending on the locale and individual, both may include any number of titles, honorifics, distinctions, or other information. \#\#\#\#\# Honorifics and Distinctions Names can incorporate honorifics to convey respect when addressing an individual. Depending on the locale, honorifics may be incorporated into a name prefix or suffix, which is usually applied to a full name or family name only. For example, the American name "Mr. Sherman" contains the honorific "Mr." as a prefix, whereas the Japanese name "夏目さん (Natsume-san)" contains the honorific "san (さん)" as a suffix. Unlike most other aspects of names, honorifics are often localized to their corresponding equivalent for another language. For example, an American person might address a Japanese person as "Mr. Natsume," and a Japanese person might address an American person as "シャーマンさん (Sherman-san)." A person that holds an academic degree, accreditation, decoration, or honor may convey that distinction through a name prefix or suffix, which can sometimes take the place of a conventional honorific. For example, the name "James Watt, FRS, FRSE" contains the postnominal letters "FRS" and "FRSE" to convey membership to learned societies. When modeling postnominal letters with 'NSPersonNameComponents', concatenate them using a locale-appropriate delimiter and set the result as the 'nameSuffix' property value. Users often prefer to be addressed informally when using an app, so the use of honorifics in names is not always appropriate. For this reason, honorifics and other distinctions typically appear in names only when a formatter specifies the most explicit style. When such formalities are appropriate, you should be aware of the particular conventions for addressing individuals in the target locale. \#\#\#\# Phonetic Representation It is sometimes beneficial to provide phonetic representations to aid in the pronunciation of names that are foreign or unfamiliar. For example, the Malay name "يوسف بن اسحاق" in Jawi script may be transliterated into Latin script as "Yusof bin Ishak" for English-speaking locales, where Latin script is commonly used. Depending on the locale and on the way the name is to be displayed to the user, it may be appropriate to provide an appropriate transliteration. This may be provided by the user or computed using the \ function, except for names in certain nonphonetic scripts. A phonetic representation may also be used to specify the pronunciation of a name in idiographic script with multiple pronunciations. For example, the character "藤" in the Japanese name "近藤 藤子 (Kondō Fujiko)" is pronounced "dō" in the family name and "fuji" in the given name, which can be clarified by providing the furigana "こんどう ふじこ" as a phonetic representation for a Japanese locale. A phonetic representation may also be appropriate for names in a script appropriate for, but unfamiliar to, a given locale. For example, for the French name "Claude Debussy" the phonetic representation "clawed deb-you-see" as a pronunciation aid to an American English-speaking locale. Use of this kind of phonetic representation is discouraged for most user contexts. \#\#\#\#\# Aliases Individuals may have one or more valid names, or aliases. This may be the result of adopting a new name in conjunction with a life event, such as marriage. For example, the name "Marie Curie" could have the corresponding alias "Maria Salomea Skłodowska." Because each alias represents a separate name, an individual with one or more aliases would be modeled by a corresponding of number of 'NSPersonNameComponents' objects, each representing a single alias. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,37 +44,37 @@ namespace cocoon explicit PersonNameComponents(Adopt adopt); /** * @brief Returns the `familyName` property of `NSPersonNameComponents`. - * @details Name passed from one generation to another to indicate lineage, e.g. Appleseed. + * @details Name passed from one generation to another to indicate lineage, e.g. Appleseed * @return The converted Objective-C result. */ std::string family_name() const; /** * @brief Sets the `familyName` property of `NSPersonNameComponents`. - * @details Name passed from one generation to another to indicate lineage, e.g. Appleseed. + * @details Name passed from one generation to another to indicate lineage, e.g. Appleseed * @param value Argument converted to the Objective-C parameter of the same role. */ void set_family_name(const std::string& value) const; /** * @brief Returns the `givenName` property of `NSPersonNameComponents`. - * @details Name bestowed upon an individual by one's parents, e.g. Johnathan. + * @details Name bestowed upon an individual by one's parents, e.g. Johnathan * @return The converted Objective-C result. */ std::string given_name() const; /** * @brief Sets the `givenName` property of `NSPersonNameComponents`. - * @details Name bestowed upon an individual by one's parents, e.g. Johnathan. + * @details Name bestowed upon an individual by one's parents, e.g. Johnathan * @param value Argument converted to the Objective-C parameter of the same role. */ void set_given_name(const std::string& value) const; /** * @brief Returns the `middleName` property of `NSPersonNameComponents`. - * @details Secondary given name chosen to differentiate those with the same first name, e.g. Maple. + * @details Secondary given name chosen to differentiate those with the same first name, e.g. Maple * @return The converted Objective-C result. */ std::string middle_name() const; /** * @brief Sets the `middleName` property of `NSPersonNameComponents`. - * @details Secondary given name chosen to differentiate those with the same first name, e.g. Maple. + * @details Secondary given name chosen to differentiate those with the same first name, e.g. Maple * @param value Argument converted to the Objective-C parameter of the same role. */ void set_middle_name(const std::string& value) const; @@ -105,25 +104,25 @@ namespace cocoon void set_name_suffix(const std::string& value) const; /** * @brief Returns the `nickname` property of `NSPersonNameComponents`. - * @details Name substituted for the purposes of familiarity, e.g. "Johnny". + * @details Name substituted for the purposes of familiarity, e.g. "Johnny" * @return The converted Objective-C result. */ std::string nickname() const; /** * @brief Sets the `nickname` property of `NSPersonNameComponents`. - * @details Name substituted for the purposes of familiarity, e.g. "Johnny". + * @details Name substituted for the purposes of familiarity, e.g. "Johnny" * @param value Argument converted to the Objective-C parameter of the same role. */ void set_nickname(const std::string& value) const; /** * @brief Returns the `phoneticRepresentation` property of `NSPersonNameComponents`. - * @details The phonetic representation of the name components. Each element of the phonetic representation should correspond to an element of the original 'NSPersonNameComponents' instance. The phonetic representation of the phonetic representation object itself will be ignored. 'nil' by default; must be instantiated. + * @details Each element of the phoneticRepresentation should correspond to an element of the original PersonNameComponents instance. The phoneticRepresentation of the phoneticRepresentation object itself will be ignored. nil by default, must be instantiated. * @return The converted Objective-C result. */ PersonNameComponents phonetic_representation() const; /** * @brief Sets the `phoneticRepresentation` property of `NSPersonNameComponents`. - * @details The phonetic representation of the name components. Each element of the phonetic representation should correspond to an element of the original 'NSPersonNameComponents' instance. The phonetic representation of the phonetic representation object itself will be ignored. 'nil' by default; must be instantiated. + * @details Each element of the phoneticRepresentation should correspond to an element of the original PersonNameComponents instance. The phoneticRepresentation of the phoneticRepresentation object itself will be ignored. nil by default, must be instantiated. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_phonetic_representation(const PersonNameComponents& value) const; diff --git a/include/generated/person_name_components_formatter.h b/include/generated/person_name_components_formatter.h index 83ba6736..c191e636 100644 --- a/include/generated/person_name_components_formatter.h +++ b/include/generated/person_name_components_formatter.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPersonNameComponentsFormatter` (Foundation). - * @details A formatter that provides localized representations of the components of a person's name. Each locale has its own set of rules and conventions for how personal names are structured and represented. These rules vary widely across different locales in a several ways, including the sort and display order of given and family names, the use of salutations and honorifics, and other concerns related to the grammar, spelling, punctuation, and formatting. About the only thing that is consistent across all locales is that personal names are significant and meaningful. For this reason, names deserve careful and respectful treatment—perhaps more than any other kind of information your app interacts with. Formatters can be configured to represent names in a variety of styles, which are described in detail below. - Default (''Style/default'') - Short (''Style/short'') - Long (''Style/long'') - Abbreviated (''Style/abbreviated'') When determining how to represent a name in a particular style, a formatter takes a number of factors into consideration, in order of priority: 1. Script derived behaviors Scripts may specify a strict sort or display order of given and family names, and the availability of styles. 2. User specified preferences Users can enable and configure the display of short names, as well as whether or not to display nicknames when available. Users can also override the default sort and display order of given and family names for their current locale. 3. Locale derived defaults Locales specify a default sort and display order for given and family names. 4. Developer specified configuration The style property value set for the 'NSPersonNameComponentsFormatter' object. When the behavior specified in one factor conflicts with any other factors, the behavior specified by the factor with the most precedence is used. For example, the U.S. English ('en-US') locale specifies that names be displayed in "given name followed by the family name" (for example,"John Appleseed"). This behavior would be overridden if the user changed their system preferences to have names displayed as family name followed by given name (for example, "Appleseed, John"), because user-specified preferences take precedence over locale-derived defaults. Furthermore, if the name to be formatted were Japanese (for example, given name: "泰夫", family name: "木田"), the behavior derived for the name's script (CJK, for Chinese, Japanese, and Korean languages) would take precedence over any locale-derived defaults or user-specified preferences to have the name displayed as family name followed by given name (for example, "木田 泰夫"). These considerations extend to the availability of certain formatter styles as well. Because developer-specified configurations have the lowest precedence in determining behavior, the value set for the formatter's style property can be invalidated if it's not supported for the locale, user preferences, or script. If the specified style is not available, the next longest valid style is used. For example, a name in Arabic script (for example, "أحمد الراجحي") does not support the Abbreviated style, so the Short style is used instead. A name that contains more than one script (for example, given name: "John", family name: "王") is detected to have "Unknown" script, which has its own set of behaviors and characteristics. > Tip: > In Swift, you can use ''PersonNameComponents/FormatStyle'' rather than ''PersonNameComponentsFormatter''. The ''FormatStyle'' API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ''FormatStyle'' instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters. \#\#\# Styles 'NSPersonNameComponentsFormatter' can be configured to format names in the following styles: - term ''Style/default'': The minimally necessary features for differentiation in a casual setting. Equivalent to ''Style/medium''. - term ''Style/short'': Relies on user preferences and language defaults to display shortened form appropriate for display in space-constrained settings. - term ''Style/long'': The fully qualified name complete with all known components. - term ''Style/abbreviated'': The maximally abbreviated form of a name. | | 'namePrefix' | 'givenName' | 'middleName' | 'familyName' | 'nameSuffix' | 'nickname' | |---|---|---|---|---|---|---| | Arabic ![](spacer) '(ar-SA)' | .د | أحمد | | محمدالمصري | | | | Chinese ![](spacer) '(zh-Hans)' | 物理学博士 | 振宁 | | 杨 | 先生 | | | English ![](spacer) '(en-US)' | Dr. | Jonathan | Maple | Appleseed | Esq. | Johnny | | French ![](spacer) '(fr-FR)' | Père | Jean-Philippe | | de Zélicourt | | JP | | German ![](spacer) '(de-DE)' | Dr. med. | Max | | Mustermann | junior, M.A. | | | Hindi ![](spacer) '(hi-IN)' | डॉ. | रिय | | साहिल | | | | Japanese ![](spacer) '(ja-JP)' | | 泰夫 | | 木田 | 先生 | | | Spanish ![](spacer) '(es-ES)' | Dr. | José Ramiro | | Martín González de Rivera | júnior, PhD | Ramiro | | Thai ![](spacer) '(th-TH)' | ฯพณฯ | สมชาย | ปีเตอร์ | รัตนเรืองรองบวรทิพย์ | | | \#\#\#\# Default The Default, or Medium, style presents names in a way that is suitable for most contexts. It uses the given and family names, as well as a nickname, if provided and enabled by the user in System Preferences. | | Default style | |---|---| | Arabic (ar-SA) | أحمد محمﺩﺍلمصﺭﻱ | | Chinese (zh-Hans) | 杨振宁 | | English (en-US) | Jonathan Appleseed | | French (fr-FR) | Jean-Philippe de Zélicourt | | German (de-DE) | Max Mustermann | | Hindi (hi-IN) | रिय साहिल | | Japanese (ja-JP) | 木田泰夫 | | Spanish (es-ES) | José Ramiro Martín González de Rivera | | Thai (th-TH) | สมชาย รัตนเรืองรอง บวรทิพย์ | \#\#\#\# Short The Short style offers an alternative display method for names whose default representation may exceed a certain length constraint. It is only available if the user has enabled "Short Names" in System Preferences, and only for names with a script that supports Short style. Otherwise, a formatter configured to display with Short style is displayed with Medium style instead. If a user has enabled the use of short names, the user can choose from one of four variations: - Given Name - Family Initial - Family Name - Given Initial - Given Name Only - Family Name Only Short style is not available for names in CJK script and is restricted to Given Name Only or Family Name Only for names in Arabic or Devanagari script. If the specified Short style is unavailable, the Medium style is used instead. | | Given Name - Family Initial | Family Name - Given Initial | Given Name Only | Family Name Only | |---|---|---|---|---| | Arabic (ar-SA) | N/A | N/A | أحمد | محمﺩﺍلمصﺭﻱ | | Chinese (zh-Hans) | N/A | N/A | N/A | N/A | | English (en-US) | Jonathan A | J Appleseed | Jonathan | Appleseed | | French (fr-FR) | Jean-Philippe d | J de Zélicourt | Jean-Philippe | de Zélicourt | | German (de-DE) | Max M | M Mustermann | Max | Mustermann | | Hindi (hi-IN) | N/A | N/A | रिय | साहिल | | Japanese (ja-JP) | N/A | N/A | N/A | N/A | | Spanish (es-ES) | José Ramiro M | J Martín González de Rivera | José Ramiro | Martín González de Rivera | | Thai (th-TH) | สมชาย ร | ส รัตนเรืองรองบวรทิพย์ | สมชาย | รัตนเรืองรองบวรทิพย์ | > Important: > 'NSPersonNameComponentsFormatter' does not currently account for prepositional particles. Representations using the Short style that specify a family name initial naively use the first letter unit of the particle as the initial. \#\#\#\# Long The Long style provides the most explicit representation of names. It uses all available name components, with the exception of nickname. | | Long style | |---|---| | Arabic (ar-SA) | ﺩ. أحمد محمﺩﺍلمصﺭﻱ | | Chinese (zh-Hans) | 物理学博士杨振宁先生 | | English (en-US) | Dr. Jonathan Maple Appleseed Esq. | | French (fr-FR) | Père Jean-Philippe de Zélicourt | | German (de-DE) | Dr. med. Max Mustermann junior, M.A. | | Hindi (hi-IN) | डॉ. रिय साहिल | | Japanese (ja-JP) | 木田泰夫先生 | | Spanish (es-ES) | Dr. José Ramiro Martín González de Rivera júnior, PhD | | Thai (th-TH) | ฯพณฯ สมชาย ปีเตอร์ รัตนเรืองรอง บวรทิพย์ | \#\#\#\# Abbreviated The Abbreviated style offers the most compact representation of names, similar to a monogram. Abbreviated style is supported for names in several scripts, with the following general characteristics: - For names in Cyrillic, Greek, or Latin script, the first characters of 'givenName', 'middleName', and 'familyName' may be used. - For names in Chinese or Japanese script, 'familyName' may be used. If 'familyName' is too long, or if the family name is 'nil', the Short or Medium style may be used instead. - For names in Korean script, 'givenName' may be used. If 'givenName' is too long, the first character of 'givenName' may be used. If 'givenName' is 'nil', the 'familyName' may be used instead. - For names in Bengali, Devanagari, Gujarati, Gurmukhi, Kannada, Malayalam, Oriya, Sinhala, Tamil, Telugu, Tibetan, or Thai script, the first character of 'givenName' may be used. If 'givenName' is 'nil', the first character of 'familyName' may be used instead. - For names that contain more than one script, the abbreviated style may use the 'familyName', 'givenName', or the first characters of 'givenName' and/or 'familyName'. If the Abbreviated style is unavailable, the Short style is used instead—unless that too is unsupported, in which case the Medium style is used instead. | | Abbreviated style | |---|---| | Arabic (ar-SA) | N/A | | Chinese (zh-Hans) | 杨 | | English (en-US) | JMA | | French (fr-FR) | Jd | | German (de-DE) | MM | | Hindi (hi-IN) | मि | | Japanese (ja-JP) | 木田 | | Spanish (es-ES) | JM | | Thai (th-TH) | ส | > Important: > 'NSPersonNameComponentsFormatter' doesn't currently account for prepositional particles or compound names. Representations using the Abbreviated style uses the first letter unit of each name component, regardless. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -53,14 +52,14 @@ namespace cocoon explicit PersonNameComponentsFormatter(Adopt adopt); /** * @brief Calls `-[NSPersonNameComponentsFormatter annotatedStringFromPersonNameComponents:]`. - * @details Returns an attributed string with annotations for each component. For each range, attributes can be obtained by querying dictionary key 'NSPersonNameComponentKey', using 'NSPersonNameComponent' constant values. + * @details Returns attributed string with annotations for each component. For each range, attributes can be obtained by querying dictionary key NSPersonNameComponentKey , using NSPersonNameComponent constant values. * @param components Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AttributedString annotated_string_from_person_name_components(const PersonNameComponents& components) const; /** * @brief Calls `+[NSPersonNameComponentsFormatter localizedStringFromPersonNameComponents:style:options:]`. - * @details Returns a formatted string from the given person name components using the specified style and options. Shortcut for converting an 'NSPersonNameComponents' object into a string without explicitly creating an instance. Create an instance for greater customizability. + * @details Shortcut for converting an NSPersonNameComponents object into a string without explicitly creating an instance. Create an instance for greater customizability. * @param components Argument converted to the Objective-C parameter of the same role. * @param name_format_style Argument converted to the Objective-C parameter of the same role. * @param name_options Argument converted to the Objective-C parameter of the same role. @@ -69,51 +68,51 @@ namespace cocoon static std::string localized_string_from_person_name_components(const PersonNameComponents& components, PersonNameComponentsFormatterStyle name_format_style, PersonNameComponentsFormatterOptions name_options); /** * @brief Calls `-[NSPersonNameComponentsFormatter personNameComponentsFromString:]`. - * @details Returns an 'NSPersonNameComponents' object representing the name components found in the provided string. + * @details Convenience method on getObjectValue:forString:error:. Returns an NSPersonNameComponents object representing the name components found in the provided string. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ PersonNameComponents person_name_components_from_string(const std::string& string) const; /** * @brief Calls `-[NSPersonNameComponentsFormatter stringFromPersonNameComponents:]`. - * @details Returns a string containing the formatted value of the provided components object. + * @details Convenience method on stringForObjectValue:. Returns a string containing the formatted value of the provided components object. * @param components Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_from_person_name_components(const PersonNameComponents& components) const; /** * @brief Returns the `locale` property of `NSPersonNameComponentsFormatter`. - * @details Specifies the locale to format names. Defaults to 'autoupdatingCurrentLocale'. Also resets to 'autoupdatingCurrentLocale' on assignment of 'nil'. + * @details Specifies the locale to format names. Defaults to autoupdatingCurrentLocale. Also resets to autoupdatingCurrentLocale on assignment of nil. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSPersonNameComponentsFormatter`. - * @details Specifies the locale to format names. Defaults to 'autoupdatingCurrentLocale'. Also resets to 'autoupdatingCurrentLocale' on assignment of 'nil'. + * @details Specifies the locale to format names. Defaults to autoupdatingCurrentLocale. Also resets to autoupdatingCurrentLocale on assignment of nil. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; /** * @brief Returns the `phonetic` property of `NSPersonNameComponentsFormatter`. - * @details Specify that the formatter should only format the components object's phoneticRepresentation. + * @details Specify that the formatter should only format the components object's phoneticRepresentation * @return The converted Objective-C result. */ bool is_phonetic() const; /** * @brief Sets the `phonetic` property of `NSPersonNameComponentsFormatter`. - * @details Specify that the formatter should only format the components object's phoneticRepresentation. + * @details Specify that the formatter should only format the components object's phoneticRepresentation * @param value Argument converted to the Objective-C parameter of the same role. */ void set_phonetic(bool value) const; /** * @brief Returns the `style` property of `NSPersonNameComponentsFormatter`. - * @details The formatting style for the formatted string on an instance. 'ShortStyle' will fall back to user preferences and language-specific defaults. + * @details Specify the formatting style for the formatted string on an instance. ShortStyle will fall back to user preferences and language-specific defaults * @return The converted Objective-C result. */ PersonNameComponentsFormatterStyle style() const; /** * @brief Sets the `style` property of `NSPersonNameComponentsFormatter`. - * @details The formatting style for the formatted string on an instance. 'ShortStyle' will fall back to user preferences and language-specific defaults. + * @details Specify the formatting style for the formatted string on an instance. ShortStyle will fall back to user preferences and language-specific defaults * @param value Argument converted to the Objective-C parameter of the same role. */ void set_style(PersonNameComponentsFormatterStyle value) const; diff --git a/include/generated/pipe.h b/include/generated/pipe.h index 7f92b6d7..c78e1ef0 100644 --- a/include/generated/pipe.h +++ b/include/generated/pipe.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPipe` (Foundation). - * @details A one-way communications channel between related processes. ''Pipe'' objects provide an object-oriented interface for accessing pipes. An ''Pipe'' object represents both ends of a pipe and enables communication through the pipe. A pipe is a one-way communications channel between related processes; one process writes data, while the other process reads that data. The data that passes through the pipe is buffered; the size of the buffer is determined by the underlying operating system. ''Pipe'' is an abstract class, the public interface of a class cluster. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -34,13 +33,11 @@ namespace cocoon explicit Pipe(Adopt adopt); /** * @brief Returns the `fileHandleForReading` property of `NSPipe`. - * @details The receiver's read file handle. * @return The converted Objective-C result. */ FileHandle file_handle_for_reading() const; /** * @brief Returns the `fileHandleForWriting` property of `NSPipe`. - * @details The receiver's write file handle. * @return The converted Objective-C result. */ FileHandle file_handle_for_writing() const; diff --git a/include/generated/pointer_array.h b/include/generated/pointer_array.h index 7777a9fe..d84f6637 100644 --- a/include/generated/pointer_array.h +++ b/include/generated/pointer_array.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPointerArray` (Foundation). - * @details A collection similar to an array, but with a broader range of available memory semantics. The pointer array class is modeled after ''NSArray'', but can also hold 'nil' values. You can insert or remove 'nil' values which contribute to the array's ''count''. A pointer array can be initialized to maintain strong or weak references to objects, or according to any of the memory or personality options defined by ''NSPointerFunctions/Options''. The ''NSCopying'' and ''NSCoding'' protocols are applicable only when a pointer array is initialized to maintain strong or weak references to objects. When enumerating a pointer array with ''NSFastEnumeration'' using 'for...in', the loop will yield any 'nil' values present in the array. See [Fast Enumeration Makes It Easy to Enumerate a Collection](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/FoundationTypesandCollections/FoundationTypesandCollections.html\#//apple_ref/doc/uid/TP40011210-CH7-SW30) in [Programming with Objective-C](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html\#//apple_ref/doc/uid/TP40011210) for more information. \#\#\# Subclassing Notes 'NSPointerArray' is not suitable for subclassing. + * @details NSPointerArray.h A PointerArray acts like a traditional array that slides elements on insertion or deletion. Unlike traditional arrays, it holds NULLs, which can be inserted or extracted (and contribute to count). Also unlike traditional arrays, the 'count' of the array may be set directly. Using NSPointerFunctionsWeakMemory object references will turn to NULL on last release. The copying and archiving protocols are applicable only when NSPointerArray is configured for Object uses. The fast enumeration protocol (supporting the for..in statement) will yield NULLs if present. It is defined for all types of pointers although the language syntax doesn't directly support this. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -52,75 +52,64 @@ namespace cocoon explicit PointerArray(Adopt adopt); /** * @brief Calls `-[NSPointerArray addPointer:]`. - * @details Adds a given pointer to the receiver. 'pointer' is added at index 'count'. - Parameter pointer: The pointer to add. This value may be 'NULL'. * @param pointer Argument converted to the Objective-C parameter of the same role. */ void add_pointer(void* pointer) const; /** * @brief Calls `-[NSPointerArray compact]`. - * @details Removes 'NULL' values from the receiver. */ void compact() const; /** * @brief Calls `-[NSPointerArray insertPointer:atIndex:]`. - * @details Inserts a pointer at a given index. Elements at and above 'index', including 'NULL' values, slide higher. - Parameter item: The pointer to add. - Parameter index: The index of an element in the receiver. This value must be less than the count of the receiver. * @param item Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_pointer(void* item, std::uint64_t index) const; /** * @brief Calls `-[NSPointerArray pointerAtIndex:]`. - * @details Returns the pointer at a given index. The returned value may be 'NULL'. - Parameter index: The index of an element in the receiver. This value must be less than the count of the receiver. - Returns: The pointer at 'index'. * @param index Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ void* pointer_at_index(std::uint64_t index) const; /** * @brief Calls `-[NSPointerArray removePointerAtIndex:]`. - * @details Removes the pointer at a given index. Elements above 'index', including 'NULL' values, slide lower. - Parameter index: The index of an element in the receiver. This value must be less than the count of the receiver. * @param index Argument converted to the Objective-C parameter of the same role. */ void remove_pointer_at_index(std::uint64_t index) const; /** * @brief Calls `-[NSPointerArray replacePointerAtIndex:withPointer:]`. - * @details Replaces the pointer at a given index. - Parameter index: The index of an element in the receiver. This value must be less than the count of the receiver. - Parameter item: The item with which to replace the element at 'index'. This value may be 'NULL'. * @param index Argument converted to the Objective-C parameter of the same role. * @param item Argument converted to the Objective-C parameter of the same role. */ void replace_pointer_at_index(std::uint64_t index, void* item) const; /** * @brief Calls `+[NSPointerArray strongObjectsPointerArray]`. - * @details Returns a new pointer array that maintains strong references to its elements. * @return The converted Objective-C result. */ static PointerArray strong_objects_pointer_array(); /** * @brief Calls `+[NSPointerArray weakObjectsPointerArray]`. - * @details Returns a new pointer array that maintains weak references to its elements. * @return The converted Objective-C result. */ static PointerArray weak_objects_pointer_array(); /** * @brief Returns the `allObjects` property of `NSPointerArray`. - * @details All the objects in the receiver. * @return The converted Objective-C result. */ std::vector all_objects() const; /** * @brief Returns the `count` property of `NSPointerArray`. - * @details The number of elements in the receiver. If you increase the 'count', 'NULL' values are added. If you decrease the 'count', elements at indexes 'count' and greater are removed. * @return The converted Objective-C result. */ std::uint64_t count() const; /** * @brief Sets the `count` property of `NSPointerArray`. - * @details The number of elements in the receiver. If you increase the 'count', 'NULL' values are added. If you decrease the 'count', elements at indexes 'count' and greater are removed. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_count(std::uint64_t value) const; /** * @brief Returns the `pointerFunctions` property of `NSPointerArray`. - * @details The functions in use by the receiver. The returned object is a new 'NSPointerFunctions' object that you can modify and/or use directly to create other pointer collections. + * @details return an NSPointerFunctions object reflecting the functions in use. This is a new autoreleased object that can be subsequently modified and/or used directly in the creation of other pointer "collections". * @return The converted Objective-C result. */ PointerFunctions pointer_functions() const; diff --git a/include/generated/pointer_functions.h b/include/generated/pointer_functions.h index 5ecbb109..e3204300 100644 --- a/include/generated/pointer_functions.h +++ b/include/generated/pointer_functions.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSPointerFunctions` (Foundation). - * @details An instance of 'NSPointerFunctions' defines callout functions appropriate for managing a pointer reference held somewhere else. The functions specified by an instance of 'NSPointerFunctions' are separated into two clusters—those that define "personality" such as "object" or "C-string", and those that describe memory management issues such as a memory deallocation function. There are constants for common personalities and memory manager selections (see 'Memory and Personality Options'). ''NSHashTable'', ''NSMapTable'', and ''NSPointerArray'' use an 'NSPointerFunctions' object to define the acquisition and retention behavior for the pointers they manage. Note, however, that not all combinations of personality and memory management behavior are valid for these collections. The pointer collection objects copy the 'NSPointerFunctions' object on input and output, so you cannot usefully subclass 'NSPointerFunctions'. \#\#\# Subclassing Notes 'NSPointerFunctions' is not suitable for subclassing. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -34,73 +33,61 @@ namespace cocoon explicit PointerFunctions(Adopt adopt); /** * @brief Returns the `acquireFunction` property of `NSPointerFunctions`. - * @details The function used to acquire memory. This specifies the function to use for copy-in operations. * @return The converted Objective-C result. */ auto acquire_function() const -> void* (*)(void*, std::uint64_t (*)(void*), bool); /** * @brief Sets the `acquireFunction` property of `NSPointerFunctions`. - * @details The function used to acquire memory. This specifies the function to use for copy-in operations. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_acquire_function(void* (*value)(void*, std::uint64_t (*)(void*), bool)) const; /** * @brief Returns the `descriptionFunction` property of `NSPointerFunctions`. - * @details The function used to describe elements. This function is used by description methods for hash and map tables. * @return The converted Objective-C result. */ auto description_function() const -> void* (*)(void*); /** * @brief Sets the `descriptionFunction` property of `NSPointerFunctions`. - * @details The function used to describe elements. This function is used by description methods for hash and map tables. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_description_function(void* (*value)(void*)) const; /** * @brief Returns the `hashFunction` property of `NSPointerFunctions`. - * @details The hash function. * @return The converted Objective-C result. */ auto hash_function() const -> std::uint64_t (*)(void*, std::uint64_t (*)(void*)); /** * @brief Sets the `hashFunction` property of `NSPointerFunctions`. - * @details The hash function. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_hash_function(std::uint64_t (*value)(void*, std::uint64_t (*)(void*))) const; /** * @brief Returns the `isEqualFunction` property of `NSPointerFunctions`. - * @details The function used to compare pointers. * @return The converted Objective-C result. */ auto is_equal_function() const -> bool (*)(void*, void*, std::uint64_t (*)(void*)); /** * @brief Sets the `isEqualFunction` property of `NSPointerFunctions`. - * @details The function used to compare pointers. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_is_equal_function(bool (*value)(void*, void*, std::uint64_t (*)(void*))) const; /** * @brief Returns the `relinquishFunction` property of `NSPointerFunctions`. - * @details The function used to relinquish memory. This specifies the function to use when an item is removed from a table or pointer array. * @return The converted Objective-C result. */ auto relinquish_function() const -> void (*)(void*, std::uint64_t (*)(void*)); /** * @brief Sets the `relinquishFunction` property of `NSPointerFunctions`. - * @details The function used to relinquish memory. This specifies the function to use when an item is removed from a table or pointer array. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_relinquish_function(void (*value)(void*, std::uint64_t (*)(void*))) const; /** * @brief Returns the `sizeFunction` property of `NSPointerFunctions`. - * @details The function used to determine the size of pointers. This function is used for copy-in operations (unless the collection has an object personality). * @return The converted Objective-C result. */ auto size_function() const -> std::uint64_t (*)(void*); /** * @brief Sets the `sizeFunction` property of `NSPointerFunctions`. - * @details The function used to determine the size of pointers. This function is used for copy-in operations (unless the collection has an object personality). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_size_function(std::uint64_t (*value)(void*)) const; diff --git a/include/generated/port.h b/include/generated/port.h index c79ef4fa..2aab2cc6 100644 --- a/include/generated/port.h +++ b/include/generated/port.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPort` (Foundation). - * @details An abstract class that represents a communication channel. Communication occurs between ''NSPort'' objects, which typically reside in different threads or tasks. The distributed objects system uses ''NSPort'' objects to send ''NSPortMessage'' objects back and forth. Implement interapplication communication using distributed objects whenever possible and use ''NSPort'' objects only when necessary. To receive incoming messages, add ''NSPort'' objects to an instance of ''NSRunLoop'' as input sources. ''NSConnection'' objects automatically add their receive port when initialized. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,32 +43,27 @@ namespace cocoon explicit Port(Adopt adopt); /** * @brief Calls `-[NSPort delegate]`. - * @details Returns the receiver's delegate. * @return The converted Objective-C result. */ Object delegate() const; /** * @brief Calls `-[NSPort invalidate]`. - * @details Marks the receiver as invalid and posts an ''NSPortDidBecomeInvalidNotification'' to the default notification center. */ void invalidate() const; /** * @brief Calls `-[NSPort removeFromRunLoop:forMode:]`. - * @details Removes the receiver from the run loop mode of the given run loop. You should not directly invoke this method. Instead, you should remove the port from the run loop. * @param run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void remove_from_run_loop(const RunLoop& run_loop, const std::string& mode) const; /** * @brief Calls `-[NSPort scheduleInRunLoop:forMode:]`. - * @details Schedules the receiver into a given run loop. You should not directly invoke this method. Instead, you should add the port to a run loop. * @param run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void schedule_in_run_loop(const RunLoop& run_loop, const std::string& mode) const; /** * @brief Calls `-[NSPort sendBeforeDate:components:from:reserved:]`. - * @details Attempts to send the message before a given date, treating the receiver as the send port and the given port as the receive port. * @param limit_date Argument converted to the Objective-C parameter of the same role. * @param components Argument converted to the Objective-C parameter of the same role. * @param receive_port Argument converted to the Objective-C parameter of the same role. @@ -79,7 +73,6 @@ namespace cocoon bool send_before_date(const Date& limit_date, const std::vector& components, const Port& receive_port, std::uint64_t header_space_reserved) const; /** * @brief Calls `-[NSPort sendBeforeDate:msgid:components:from:reserved:]`. - * @details Attempts to send the message with a given identifier before a given date, treating the receiver as the send port and the given port as the receive port. * @param limit_date Argument converted to the Objective-C parameter of the same role. * @param msg_id Argument converted to the Objective-C parameter of the same role. * @param components Argument converted to the Objective-C parameter of the same role. @@ -90,19 +83,16 @@ namespace cocoon bool send_before_date(const Date& limit_date, std::uint64_t msg_id, const std::vector& components, const Port& receive_port, std::uint64_t header_space_reserved) const; /** * @brief Calls `-[NSPort setDelegate:]`. - * @details Sets the receiver's delegate to a given object. * @param an_object Argument converted to the Objective-C parameter of the same role. */ void set_delegate(const Object& an_object) const; /** * @brief Returns the `reservedSpaceLength` property of `NSPort`. - * @details The number of bytes of space reserved by the receiver for sending data. * @return The converted Objective-C result. */ std::uint64_t reserved_space_length() const; /** * @brief Returns the `valid` property of `NSPort`. - * @details A Boolean value that indicates whether the receiver is valid. * @return The converted Objective-C result. */ bool is_valid() const; diff --git a/include/generated/port_coder.h b/include/generated/port_coder.h index d7d22058..ddef0c39 100644 --- a/include/generated/port_coder.h +++ b/include/generated/port_coder.h @@ -43,25 +43,21 @@ namespace cocoon explicit PortCoder(Adopt adopt); /** * @brief Calls `-[NSPortCoder decodePortObject]`. - * @details Decodes and returns a port that was previously encoded with '-encodePortObject:'. * @return The converted Objective-C result. */ Port decode_port_object() const; /** * @brief Calls `-[NSPortCoder encodePortObject:]`. - * @details Encodes a given port so that a copy or proxy of it can be decoded in another process. * @param aport Argument converted to the Objective-C parameter of the same role. */ void encode_port_object(const Port& aport) const; /** * @brief Calls `-[NSPortCoder isBycopy]`. - * @details Returns a Boolean value that indicates whether the receiver has been told to encode objects by copying them. * @return The converted Objective-C result. */ bool is_bycopy() const; /** * @brief Calls `-[NSPortCoder isByref]`. - * @details Returns a Boolean value that indicates whether the receiver has been told to encode objects by reference. * @return The converted Objective-C result. */ bool is_byref() const; diff --git a/include/generated/port_message.h b/include/generated/port_message.h index c8f9dc02..213ccf16 100644 --- a/include/generated/port_message.h +++ b/include/generated/port_message.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPortMessage` (Foundation). - * @details A low-level, operating system-independent type for inter-application (and inter-thread) messages. Port messages are used primarily by the distributed objects system. You should implement inter-application communication using distributed objects whenever possible and use ''NSPortMessage'' only when necessary. An ''NSPortMessage'' object has three major parts: the send and receive ports, which are ''NSPort'' objects that link the sender of the message to the receiver, and the components, which form the body of the message. The components are held as an ''NSArray'' object containing ''NSData'' and ''NSPort'' objects. The ''send(before:)'' message sends the components out through the send port; any replies to the message arrive on the receive port. See the ''NSPort'' class specification for information on handling incoming messages. An ''NSPortMessage'' instance can be initialized with a pair of ''NSPort'' objects and an array of components. A port message's body can contain only ''NSPort'' objects or ''NSData'' objects. In the distributed objects system the byte/character arrays are usually encoded ''NSInvocation'' objects that are being forwarded from a proxy to the corresponding real object. An ''NSPortMessage'' object also maintains a message identifier, which can be used to indicate the class of a message, such as an Objective-C method invocation, a connection request, an error, and so on. Use the ''msgid'' property to access the identifier. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,38 +46,32 @@ namespace cocoon explicit PortMessage(Adopt adopt); /** * @brief Calls `-[NSPortMessage sendBeforeDate:]`. - * @details Attempts to send the message before the specified date. If the message cannot be sent immediately, the sending thread blocks until either the message is sent or 'date' is reached. Sent messages are queued to minimize blocking, but failure can occur if multiple messages are sent to a port faster than the port's owner can receive them, causing the queue to fill up. If an error other than a time out occurs, this method could raise an 'NSInvalidSendPortException', 'NSInvalidReceivePortException', or an 'NSPortSendException'. - Parameters: - date: The instant before which the message should be sent. - Returns: 'YES' if the operation is successful, otherwise 'NO' (for example, if the operation times out). * @param date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool send_before_date(const Date& date) const; /** * @brief Returns the `components` property of `NSPortMessage`. - * @details The data components of the receiver. See ''NSPortMessage'' for more information. * @return The converted Objective-C result. */ std::vector components() const; /** * @brief Returns the `msgid` property of `NSPortMessage`. - * @details The identifier for the receiver. Cooperating applications can use this to define different types of messages, such as connection requests, RPCs, errors, and so on. * @return The converted Objective-C result. */ unsigned int msgid() const; /** * @brief Sets the `msgid` property of `NSPortMessage`. - * @details The identifier for the receiver. Cooperating applications can use this to define different types of messages, such as connection requests, RPCs, errors, and so on. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_msgid(unsigned int value) const; /** * @brief Returns the `receivePort` property of `NSPortMessage`. - * @details For an outgoing message, the port on which replies to the receiver will arrive. For an incoming message, the port the receiver did arrive on. * @return The converted Objective-C result. */ Port receive_port() const; /** * @brief Returns the `sendPort` property of `NSPortMessage`. - * @details For an outgoing message, the port the receiver will send itself through. For an incoming message, the port replies to the receiver should be sent through. * @return The converted Objective-C result. */ Port send_port() const; diff --git a/include/generated/port_name_server.h b/include/generated/port_name_server.h index 5db84b53..3f3c490a 100644 --- a/include/generated/port_name_server.h +++ b/include/generated/port_name_server.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPortNameServer` (Foundation). - * @details An object-oriented interface to the port registration service used by the distributed objects system. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,14 +43,12 @@ namespace cocoon explicit PortNameServer(Adopt adopt); /** * @brief Calls `-[NSPortNameServer portForName:]`. - * @details Looks up and returns the port registered under the specified name on the local host. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Port port_for_name(const std::string& name) const; /** * @brief Calls `-[NSPortNameServer portForName:host:]`. - * @details Looks up and returns the port registered under the specified name on a given host. * @param name Argument converted to the Objective-C parameter of the same role. * @param host Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -59,7 +56,6 @@ namespace cocoon Port port_for_name(const std::string& name, const std::string& host) const; /** * @brief Calls `-[NSPortNameServer registerPort:name:]`. - * @details Registers a given port as a network service with the specified name. * @param port Argument converted to the Objective-C parameter of the same role. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -67,14 +63,12 @@ namespace cocoon bool register_port(const Port& port, const std::string& name) const; /** * @brief Calls `-[NSPortNameServer removePortForName:]`. - * @details Unregisters the port for a given name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool remove_port_for_name(const std::string& name) const; /** * @brief Calls `+[NSPortNameServer systemDefaultPortNameServer]`. - * @details Returns the default system port name server. * @return The converted Objective-C result. */ static PortNameServer system_default_port_name_server(); diff --git a/include/generated/positional_specifier.h b/include/generated/positional_specifier.h index b10ceb44..a21fc3c1 100644 --- a/include/generated/positional_specifier.h +++ b/include/generated/positional_specifier.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPositionalSpecifier` (Foundation). - * @details A specifier for an insertion point in a container relative to another object in the container. Instances of 'NSPositionalSpecifier' specify an insertion point in a container relative to another object in the container, for example, 'before first word' or 'after paragraph 4'. The container is specified by an instance of 'NSScriptObjectSpecifier'. 'NSPositionalSpecifier' objects commonly encapsulate object specifiers used as arguments to the 'make' ('create') and 'move' commands and indicate where the created or moved object is to be inserted relative to the object represented by an object specifier. Invoking an accessor method to obtain information about an instance of 'NSPositionalSpecifier' causes the object to be evaluated if it hasn't been already. You don't normally subclass 'NSPositionalSpecifier'. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,48 +44,40 @@ namespace cocoon explicit PositionalSpecifier(Adopt adopt); /** * @brief Calls `-[NSPositionalSpecifier evaluate]`. - * @details Evaluates this positional specifier. */ void evaluate() const; /** * @brief Calls `-[NSPositionalSpecifier setInsertionClassDescription:]`. - * @details Sets the class description for the object or objects to be inserted. * @param class_description Argument converted to the Objective-C parameter of the same role. */ void set_insertion_class_description(const ScriptClassDescription& class_description) const; /** * @brief Returns the `insertionContainer` property of `NSPositionalSpecifier`. - * @details The container into which insertion should be done, if evaluation has been successful. * @return The converted Objective-C result. */ Object insertion_container() const; /** * @brief Returns the `insertionIndex` property of `NSPositionalSpecifier`. - * @details The index at which insertion should be done, if evaluation has been successful. * @return The converted Objective-C result. */ std::int64_t insertion_index() const; /** * @brief Returns the `insertionKey` property of `NSPositionalSpecifier`. - * @details The key for the to-many relationship for which insertion should be done, if evaluation has been successful. * @return The converted Objective-C result. */ std::string insertion_key() const; /** * @brief Returns the `insertionReplaces` property of `NSPositionalSpecifier`. - * @details A Boolean value that indicates whether the object to be inserted should replace the keyed, indexed object. * @return The converted Objective-C result. */ bool insertion_replaces() const; /** * @brief Returns the `objectSpecifier` property of `NSPositionalSpecifier`. - * @details The object specifier that identifies the reference object. * @return The converted Objective-C result. */ ScriptObjectSpecifier object_specifier() const; /** * @brief Returns the `position` property of `NSPositionalSpecifier`. - * @details The insertion position. * @return The converted Objective-C result. */ InsertionPosition position() const; diff --git a/include/generated/predicate.h b/include/generated/predicate.h index 2d96276a..9509c3c2 100644 --- a/include/generated/predicate.h +++ b/include/generated/predicate.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSPredicate` (Foundation). - * @details A definition of logical conditions for constraining a search for a fetch or for in-memory filtering. Predicates represent logical conditions, which you can use to filter collections of objects. Although it's common to create predicates directly from instances of ''NSComparisonPredicate'', ''NSCompoundPredicate'', and ''NSExpression'', you often create predicates from a format string that the class methods parse on ''NSPredicate''. Examples of predicate format strings include: - Simple comparisons, such as 'grade == "7"' or 'firstName like "Juan"' - Case- and diacritic-insensitive lookups, such as 'name contains[cd] "stein"' - Logical operations, such as '(firstName like "Mei") OR (lastName like "Chen")' - Temporal range constraints, such as 'date between {$YESTERDAY, $TOMORROW}' - Relational conditions, such as 'group.name like "work"' - Aggregate operations, such as '\@sum.items.price \< 1000' For a complete syntax reference, refer to the [Predicate Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Predicates/AdditionalChapters/Introduction.html\#//apple_ref/doc/uid/TP40001789). You can also create predicates that include variables using the ''evaluate(with:substitutionVariables:)'' method so that you can predefine the predicate before substituting concrete values at runtime. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,7 +47,6 @@ namespace cocoon explicit Predicate(Adopt adopt); /** * @brief Calls `-[NSPredicate allowEvaluation]`. - * @details Forces a securely decoded predicate to allow evaluation. When securely decoding 'NSPredicate' objects encoded using 'NSSecureCoding', evaluation is disabled because it is potentially unsafe to evaluate predicates you get out of an archive. Before you enable evaluation, you should validate key paths, selectors, and other details to ensure no erroneous or malicious code will be executed. Once you've verified the predicate, you can enable the receiver for evaluation by calling 'allowEvaluation'. */ void allow_evaluation() const; /** @@ -59,14 +57,12 @@ namespace cocoon bool allow_evaluation_with_validator(const Object& validator) const; /** * @brief Calls `-[NSPredicate evaluateWithObject:]`. - * @details Returns a Boolean value that indicates whether the specified object matches the conditions that the predicate specifies. * @param object Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool evaluate_with_object(const Object& object) const; /** * @brief Calls `-[NSPredicate evaluateWithObject:substitutionVariables:]`. - * @details Returns a Boolean value that indicates whether the specified object matches the conditions that the predicate specifies after substituting in the values from a specified variables dictionary. This method returns the same result as the two step process of first invoking 'predicateWithSubstitutionVariables:' on the predicate and then invoking 'evaluateWithObject:' on the returned value. This method is optimized for situations which require repeatedly evaluating a predicate with substitution variables with different variable substitutions. * @param object Argument converted to the Objective-C parameter of the same role. * @param bindings Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -74,21 +70,18 @@ namespace cocoon bool evaluate_with_object(const Object& object, const std::map& bindings) const; /** * @brief Calls `+[NSPredicate predicateFromMetadataQueryString:]`. - * @details Creates a predicate with a metadata query string. * @param query_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Predicate predicate_from_metadata_query_string(const std::string& query_string); /** * @brief Calls `-[NSPredicate predicateWithSubstitutionVariables:]`. - * @details Returns a copy of the predicate and substitutes the predicates variables with specified values from a specified substitution variables dictionary. The predicate itself is not modified by this method, so you can reuse it for any number of substitutions. * @param variables Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Predicate predicate_with_substitution_variables(const std::map& variables) const; /** * @brief Returns the `predicateFormat` property of `NSPredicate`. - * @details The predicate's format string. The return value of this property is not guaranteed to be the same as the string used to create the predicate using 'predicateWithFormat:' or similar methods. * @return The converted Objective-C result. */ std::string predicate_format() const; diff --git a/include/generated/presentation_intent.h b/include/generated/presentation_intent.h index 95a21259..e66ee01b 100644 --- a/include/generated/presentation_intent.h +++ b/include/generated/presentation_intent.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPresentationIntent` (Foundation). - * @details A type that contains the Markdown formatting for blocks of text, like paragraphs, lists, code blocks, and parts of tables. An ''NSPresentationIntent'' object stores the Markdown semantics for a range of characters in an attributed string. When parsing Markdown into an attributed string, the system sets the value of the ''NSAttributedString/Key/presentationIntentAttributeName'' attribute to an instance of this class. When displaying your string in system views, the system applies a default visual style to match the corresponding information in this type. To replace the system's default formatting, remove these attributes from your attributed string and apply the formatting you want. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -42,7 +41,6 @@ namespace cocoon explicit PresentationIntent(Adopt adopt); /** * @brief Calls `+[NSPresentationIntent blockQuoteIntentWithIdentity:nestedInsideIntent:]`. - * @details Creates a block quote intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - parent: The parent intent of the block quote. - Returns: A new intent with the kind set to 'NSPresentationIntentKindBlockQuote'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -50,7 +48,6 @@ namespace cocoon static PresentationIntent block_quote_intent_with_identity(std::int64_t identity, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent codeBlockIntentWithIdentity:languageHint:nestedInsideIntent:]`. - * @details Creates a code-block intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - languageHint: The programming language for the code listing. - parent: The parent intent of the code block. - Returns: A new intent with the kind set to 'NSPresentationIntentKindCodeBlock'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param language_hint Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. @@ -59,7 +56,6 @@ namespace cocoon static PresentationIntent code_block_intent_with_identity(std::int64_t identity, const std::string& language_hint, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent headerIntentWithIdentity:level:nestedInsideIntent:]`. - * @details Creates a header intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - level: The level for the header section. Specify '1' or greater for this parameter. Don't specify '0'. - parent: The parent intent of the header. - Returns: A new intent with the kind set to 'NSPresentationIntentKindHeader'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param level Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. @@ -68,14 +64,13 @@ namespace cocoon static PresentationIntent header_intent_with_identity(std::int64_t identity, std::int64_t level, const PresentationIntent& parent); /** * @brief Calls `-[NSPresentationIntent isEquivalentToPresentationIntent:]`. - * @details Returns a Boolean value that indicates whether the current intent is equivalent to the specified intent. Two intents are equivalent if their attributes match. This method doesn't consider the 'identity' property of the intents when determining their equivalence. - Parameter other: The other intent to use in the comparison. - Returns: 'YES' if the current intent is equivalent to the specified intent, or 'NO' if it isn't. + * @details Returns 'YES' if this intent is equivalent to the other presentation intent. Equivalence is the same as equality except that identity is not taken into account. * @param other Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equivalent_to_presentation_intent(const PresentationIntent& other) const; /** * @brief Calls `+[NSPresentationIntent listItemIntentWithIdentity:ordinal:nestedInsideIntent:]`. - * @details Creates a list item intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - ordinal: The ordinal number of the list item. - parent: The parent intent of the list item. - Returns: A new intent with the kind set to 'NSPresentationIntentKindListItem'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param ordinal Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. @@ -84,7 +79,6 @@ namespace cocoon static PresentationIntent list_item_intent_with_identity(std::int64_t identity, std::int64_t ordinal, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent orderedListIntentWithIdentity:nestedInsideIntent:]`. - * @details Creates an ordered list intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - parent: The parent intent of the ordered list. - Returns: A new intent with the kind set to 'NSPresentationIntentKindOrderedList'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -92,7 +86,6 @@ namespace cocoon static PresentationIntent ordered_list_intent_with_identity(std::int64_t identity, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent paragraphIntentWithIdentity:nestedInsideIntent:]`. - * @details Creates a paragraph intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - parent: The parent intent of the paragraph. - Returns: A new intent with the kind set to 'NSPresentationIntentKindParagraph'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -100,7 +93,6 @@ namespace cocoon static PresentationIntent paragraph_intent_with_identity(std::int64_t identity, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent tableCellIntentWithIdentity:column:nestedInsideIntent:]`. - * @details Creates a table cell intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - column: The column number (0-based). - parent: The parent intent of the table cell. - Returns: A new intent with the kind set to 'NSPresentationIntentKindTableCell'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param column Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. @@ -109,7 +101,6 @@ namespace cocoon static PresentationIntent table_cell_intent_with_identity(std::int64_t identity, std::int64_t column, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent tableHeaderRowIntentWithIdentity:nestedInsideIntent:]`. - * @details Creates a table header row intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - parent: The parent intent of the table header row. - Returns: A new intent with the kind set to 'NSPresentationIntentKindTableHeaderRow'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -117,7 +108,6 @@ namespace cocoon static PresentationIntent table_header_row_intent_with_identity(std::int64_t identity, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent tableIntentWithIdentity:columnCount:alignments:nestedInsideIntent:]`. - * @details Creates a table intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - columnCount: The number of columns in the table. - alignments: An array of 'NSNumber' values indicating the alignment of each column. - parent: The parent intent of the table. - Returns: A new intent with the kind set to 'NSPresentationIntentKindTable'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param column_count Argument converted to the Objective-C parameter of the same role. * @param alignments Argument converted to the Objective-C parameter of the same role. @@ -127,7 +117,6 @@ namespace cocoon static PresentationIntent table_intent_with_identity(std::int64_t identity, std::int64_t column_count, const std::vector& alignments, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent tableRowIntentWithIdentity:row:nestedInsideIntent:]`. - * @details Creates a table row intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - row: The row number (0-based). - parent: The parent intent of the table row. - Returns: A new intent with the kind set to 'NSPresentationIntentKindTableRow'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param row Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. @@ -136,7 +125,6 @@ namespace cocoon static PresentationIntent table_row_intent_with_identity(std::int64_t identity, std::int64_t row, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent thematicBreakIntentWithIdentity:nestedInsideIntent:]`. - * @details Creates a thematic break intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - parent: The parent intent of the thematic break. - Returns: A new intent with the kind set to 'NSPresentationIntentKindThematicBreak'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -144,7 +132,6 @@ namespace cocoon static PresentationIntent thematic_break_intent_with_identity(std::int64_t identity, const PresentationIntent& parent); /** * @brief Calls `+[NSPresentationIntent unorderedListIntentWithIdentity:nestedInsideIntent:]`. - * @details Creates an unordered list intent with the provided information. - Parameters: - identity: The unique identifier for the intent. - parent: The parent intent of the unordered list. - Returns: A new intent with the kind set to 'NSPresentationIntentKindUnorderedList'. * @param identity Argument converted to the Objective-C parameter of the same role. * @param parent Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -152,67 +139,65 @@ namespace cocoon static PresentationIntent unordered_list_intent_with_identity(std::int64_t identity, const PresentationIntent& parent); /** * @brief Returns the `column` property of `NSPresentationIntent`. - * @details The column number to which the cell belongs. The value of this property is '0'-based, with the first column at '0', the second column at '1', and so on. If the intent is not a cell, this value is '0'. + * @details The column to which this cell belongs (0-based). If the intent is not a cell, this value is 0. * @return The converted Objective-C result. */ std::int64_t column() const; /** * @brief Returns the `columnAlignments` property of `NSPresentationIntent`. - * @details The alignments for the columns in a table. If the intent is not a table, the value of this property is 'nil'. + * @details If the intent is not a table, this value is 'nil'. * @return The converted Objective-C result. */ std::vector column_alignments() const; /** * @brief Returns the `columnCount` property of `NSPresentationIntent`. - * @details The number of columns in a table. If the intent is not a table, the value of this property is '0'. + * @details If the intent is not a table, this value is 0. * @return The converted Objective-C result. */ std::int64_t column_count() const; /** * @brief Returns the `headerLevel` property of `NSPresentationIntent`. - * @details The level of a header section. This value corresponds to the number of hash marks ('\#') associated with the header. If the intent is not a header, the value of this property is '0'. + * @details If the intent is not a header, this value is 0. * @return The converted Objective-C result. */ std::int64_t header_level() const; /** * @brief Returns the `identity` property of `NSPresentationIntent`. - * @details A unique identifier for the intent in the document. Use the value in this property to disambiguate attributes that apply to contiguous text. For example, you might use it to differentiate between two headers in a row with the same level. + * @details An integer value which uniquely identifies this intent in the document. Identity disambiguates attributes which apply to contiguous text -- for example, two headers in a row with the same level. It can also be used to track the location in an attributed string of a particular part of a document, even after mutation. * @return The converted Objective-C result. */ std::int64_t identity() const; /** * @brief Returns the `indentationLevel` property of `NSPresentationIntent`. - * @details The indentation level of the intent. The initial list has an indentation level of '0'. Each time you nest a new list, the indentation level increases by '1'. All elements within the same list have the same indentation level. Text outside list intents has an indentation level of '0'. + * @details The indentation level of this intent. Each nested list increases the indentation level by one; all elements within the same list (and not then nested into a child list intent) have the same indentation level. Text outside list intents has an indentation level of 0. * @return The converted Objective-C result. */ std::int64_t indentation_level() const; /** * @brief Returns the `intentKind` property of `NSPresentationIntent`. - * @details The type of the intent. * @return The converted Objective-C result. */ PresentationIntentKind intent_kind() const; /** * @brief Returns the `languageHint` property of `NSPresentationIntent`. - * @details The language associated with the code listing. If the intent is not a code block, the value of this property is 'nil'. + * @details If the intent is not a code block, this value is 'nil'. * @return The converted Objective-C result. */ std::string language_hint() const; /** * @brief Returns the `ordinal` property of `NSPresentationIntent`. - * @details The number for an item in an ordered list. If the intent is not a list, the value of this property is '0'. + * @details If the intent is not a list, this value is 0. * @return The converted Objective-C result. */ std::int64_t ordinal() const; /** * @brief Returns the `parentIntent` property of `NSPresentationIntent`. - * @details The parent of the current intent. * @return The converted Objective-C result. */ PresentationIntent parent_intent() const; /** * @brief Returns the `row` property of `NSPresentationIntent`. - * @details The row number to which this cell belongs. The value of this property is '0'-based, with the first row at '0', the second row at '1', and so on. If the intent is not a cell, this value is '0'. + * @details The row to which this cell belongs (0-based). If the intent is not a row, this value is 0. Header rows are always row 0. If the table has more rows, those start at row 1. * @return The converted Objective-C result. */ std::int64_t row() const; diff --git a/include/generated/process_info.h b/include/generated/process_info.h index 23390f0e..9997fb24 100644 --- a/include/generated/process_info.h +++ b/include/generated/process_info.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief Information about the running process (NSProcessInfo). - * @details A collection of information about the current process. Each process has a single, shared ''ProcessInfo'' object known as a process information agent that can return information such as arguments, environment variables, host name, and process name. The ''processInfo'' class method returns the shared agent for the current process. For example, the following line returns the ''ProcessInfo'' object, which then provides the name of the current process: \@TabNavigator { \@Tab("Swift") { '''swift let processName = ProcessInfo.processInfo.processName ''' } \@Tab("Objective-C") { '''objc NSString processName = [[NSProcessInfo processInfo] processName]; ''' } } > Note: > ''ProcessInfo'' is thread-safe in macOS 10.7 and later. The ''ProcessInfo'' class also includes the ''operatingSystemVersion'' property, which returns an ''OperatingSystemVersion'' structure identifying the operating system version on which the process is executing. ''ProcessInfo'' objects attempt to interpret environment variables and command-line arguments in the user's default C string encoding if they can't convert to Unicode as UTF-8 strings. If neither the Unicode nor C string conversion works, the ''ProcessInfo'' object ignores these values. \#\#\# Manage Activities The system has heuristics to improve battery life, performance, and responsiveness of applications for the benefit of the user. You can use the following methods to manage activities that give hints to the system that your application has special requirements: - ''beginActivity(options:reason:)'' - ''endActivity(:)'' - ''performActivity(options:reason:using:)'' In response to creating an activity, the system disables some or all of the heuristics so your application can finish quickly while still providing responsive behavior if the user needs it. You use activities when your application performs a long-running operation. If the activity can take different amounts of time (for example, calculating the next move in a chess game), it should use this API to ensure correct behavior when the amount of data or the capabilities of the user's computer varies. Activities fall into two major categories: - User-initiated activities are explicitly started by the user. Examples include exporting or downloading a user-specified file. - Background activities perform the normal operations of your application and aren't explicitly started by the user. Examples include autosaving, indexing, and automatic downloading of files. In addition, if your application requires high priority input/output (I/O), you can include the ''ActivityOptions/latencyCritical'' flag (using a bitwise 'OR'). You should only use this flag for activities like audio or video recording that require high priority I/O. If your activity takes place synchronously inside an event callback on the main thread, you don't need to use this API. Be aware that failing to end these activities for an extended period of time can have significant negative impacts on the performance of your user's computer, so be sure to use only the minimum amount of time required. User preferences may override your application's request. You can also use this API to control automatic termination or sudden termination (see \). For example, the following code brackets the work to protect it from sudden termination: \@TabNavigator { \@Tab("Swift") { '''swift let activity = ProcessInfo.processInfo.beginActivity( options: .automaticTerminationDisabled, reason: "Good Reason") // Perform some work. ProcessInfo.processInfo.endActivity(activity) ''' } \@Tab("Objective-C") { '''objc id activity = [[NSProcessInfo processInfo] beginActivityWithOptions:NSActivityAutomaticTerminationDisabled reason:\@"Good Reason"]; // Perform some work. [[NSProcessInfo processInfo] endActivity:activity]; ''' } } The above example is equivalent to the following code, which uses the ''disableAutomaticTermination(:)'' method: \@TabNavigator { \@Tab("Swift") { '''swift ProcessInfo.processInfo.disableAutomaticTermination("Good Reason") // Perform some work. ProcessInfo.processInfo.enableAutomaticTermination("Good Reason") ''' } \@Tab("Objective-C") { '''objc [[NSProcessInfo processInfo] disableAutomaticTermination:\@"Good Reason"]; // Perform some work. [[NSProcessInfo processInfo] enableAutomaticTermination:\@"Good Reason"]; ''' } } Because this API returns an object, it may be easier to pair begins and ends than when using the automatic termination API. If your app deallocates the object before the ''endActivity(:)'' call, the activity ends automatically. This API also provides a mechanism to disable system-wide idle sleep and display idle sleep. These can have a large impact on the user experience, so be careful to end activities that disable sleep (including ''ActivityOptions/userInitiated''). \#\#\# Support Sudden Termination macOS 10.6 and later includes a mechanism that allows the system to log out or shut down more quickly by, whenever possible, killing applications instead of requesting that they quit themselves. Your application can enable this capability on a global basis and then manually override its availability during actions that could cause data corruption or a poor user experience by allowing sudden termination. Alternatively, your application can manually enable and disable this functionality. Creating a process assigns a counter that indicates if the process is safe to terminate. You decrement and increment the counter using the methods ''enableSuddenTermination()'' and ''disableSuddenTermination()''. A value of '0' enables the system to terminate the process without first sending a notification or event. Your application can support sudden termination upon launch by adding a key to the application's 'Info.plist' file. If the \ key exists in the 'Info.plist' file and has a value of \, it's the equivalent of calling ''enableSuddenTermination()'' during your application launch. This allows the system to terminate the process immediately. You can still override this behavior by invoking ''disableSuddenTermination()''. Typically, you disable sudden termination whenever your app defers work that the app must complete before it terminates. If, for example, your app defers writing data to disk and enables sudden termination, you should bracket the sensitive operations with a call to ''disableSuddenTermination()'', perform the necessary operations, and then send a balancing ''enableSuddenTermination()'' message. In agents or daemon executables that don't depend on AppKit, you can manually invoke ''enableSuddenTermination()'' right away. You can then use the enable and disable methods whenever the process has work it must do before it terminates. Some AppKit functionality automatically disables sudden termination on a temporary basis to ensure data integrity. - ''UserDefaults'' temporarily disables sudden termination to prevent the process from terminating between the time at which it sets the default and the time at which it writes the preferences file — including that default — to disk. - \ temporarily disables sudden termination to prevent the process from terminating between the time at which the user has made a change to a document and the time at which \ writes the user's change to disk. > Tip: > You can determine the value of the sudden termination using the following LLDB command. > > '''objc > print (long)[[NSClassFromString(\@"NSProcessInfo") processInfo] suddenTerminationDisablingCount] > ''' > > Don't attempt to invoke or override 'suddenTerminationDisablingCount' (a private method) in your application. It's there for this debugging purpose and may disappear at any time. \#\#\# Monitor Thermal State to Adjust App Performance Thermal state indicates the level of heat generated by logic components as they run apps. As the thermal state increases, the system decreases heat by reducing the speed of the processors. Optimize your app's performance by monitoring the thermal state and reducing system usage as the thermal state increases. Query the current state with ''thermalState'' to determine if your app needs to reduce system usage. You can register the ''thermalStateDidChangeNotification'' for notifications of a change in thermal state. For recommended actions, see ''ThermalState''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,7 +43,7 @@ namespace cocoon explicit ProcessInfo(Adopt adopt); /** * @brief Calls `-[NSProcessInfo beginActivityWithOptions:reason:]`. - * @details Begins an activity using the given options and reason. Indicate completion of the activity by calling ''endActivity(:)'' passing the returned object as the argument. - Parameters: - options: Options for the activity. See ''ProcessInfo/ActivityOptions'' for possible values. - reason: A string used in debugging to indicate the reason the activity began. - Returns: An object token representing the activity. + * @details Pass in an activity to this API, and a non-NULL, non-empty reason string. Indicate completion of the activity by calling the corresponding endActivity: method with the result of the beginActivityWithOptions:reason: method. The reason string is used for debugging. * @param options Argument converted to the Objective-C parameter of the same role. * @param reason Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -52,42 +51,39 @@ namespace cocoon Object begin_activity_with_options(ActivityOptions options, const std::string& reason) const; /** * @brief Calls `-[NSProcessInfo disableAutomaticTermination:]`. - * @details Disables automatic termination for the application. This method increments the automatic termination counter. When the counter is greater than '0', the application is considered active and ineligible for automatic termination. For example, you could disable automatic termination when the user of an instant messaging application signs on, because the application requires a background connection to be maintained even if the application is otherwise inactive. The reason parameter is used to track why an application is or is not automatically terminable and can be inspected by debugging tools. A given reason can be used more than once at the same time. - Parameters: - reason: The reason why automatic termination is being disabled. + * @details Increment or decrement the counter tracking the number of automatic quit opt-out requests. When this counter is greater than zero, the app will be considered 'active' and ineligible for automatic termination. An example of using this would be disabling autoquitting when the user of an instant messaging application signs on, due to it requiring a background connection to be maintained even if the app is otherwise inactive. Each pair of calls should have a matching "reason" argument, which can be used to easily track why an application is or is not automatically terminable. A given reason can be used more than once at the same time (for example: two files are transferring over the network, each one disables automatic termination with the reason \@"file transfer in progress") * @param reason Argument converted to the Objective-C parameter of the same role. */ void disable_automatic_termination(const std::string& reason) const; /** * @brief Calls `-[NSProcessInfo disableSuddenTermination]`. - * @details Disables the application for quick killing using sudden termination. This method increments the sudden termination counter. When the termination counter reaches '0' the application allows sudden termination. By default the sudden termination counter is set to 1. This can be overridden in your application Info.plist. See \ for more information and debugging suggestions. + * @details Disable or reenable the ability to be quickly killed. The default implementations of these methods increment or decrement, respectively, a counter whose value is 1 when the process is first created. When the counter's value is 0 the application is considered to be safely killable and may be killed by the operating system without any notification or event being sent to the process first. If an application's Info.plist has an NSSupportsSuddenTermination entry whose value is true then NSApplication invokes -enableSuddenTermination automatically during application launch, which typically renders the process killable right away. You can also manually invoke -enableSuddenTermination right away in, for example, agents or daemons that don't depend on AppKit. After that, you can invoke these methods whenever the process has work it must do before it terminates. For example: - NSUserDefaults uses these to prevent process killing between the time at which a default has been set and the time at which the preferences file including that default has been written to disk. - NSDocument uses these to prevent process killing between the time at which the user has made a change to a document and the time at which the user's change has been written to disk. - You can use these whenever your application defers work that must be done before the application terminates. If for example your application ever defers writing something to disk, and it has an NSSupportsSuddenTermination entry in its Info.plist so as not to contribute to user-visible delays at logout or shutdown time, it must invoke -disableSuddenTermination when the writing is first deferred and -enableSuddenTermination after the writing is actually done. */ void disable_sudden_termination() const; /** * @brief Calls `-[NSProcessInfo enableAutomaticTermination:]`. - * @details Enables automatic termination for the application. This method decrements the automatic termination counter. When the counter is '0', the application is eligible for automatic termination. The reason parameter is used to track why an application is or is not automatically terminable and can be inspected by debugging tools. A given reason can be used more than once at the same time. - Parameters: - reason: The reason why automatic termination is being enabled. * @param reason Argument converted to the Objective-C parameter of the same role. */ void enable_automatic_termination(const std::string& reason) const; /** * @brief Calls `-[NSProcessInfo enableSuddenTermination]`. - * @details Enables the application for quick killing using sudden termination. This method decrements the sudden termination counter. When the termination counter reaches '0' the application allows sudden termination. By default the sudden termination counter is set to 1. This can be overridden in your application Info.plist. See \ for more information and debugging suggestions. */ void enable_sudden_termination() const; /** * @brief Calls `-[NSProcessInfo endActivity:]`. - * @details Ends the given activity. - Parameters: - activity: An activity object returned by ''beginActivity(options:reason:)''. + * @details The argument to this method is the result of beginActivityWithOptions:reason:. * @param activity Argument converted to the Objective-C parameter of the same role. */ void end_activity(const Object& activity) const; /** * @brief Calls `-[NSProcessInfo isOperatingSystemAtLeastVersion:]`. - * @details Returns a Boolean value indicating whether the version of the operating system on which the process is executing is the same or later than the given version. This method accounts for major, minor, and update versions of the operating system. - Parameters: - version: The operating system version to test against. - Returns: 'true' if the operating system on which the process is executing is the same or later than the given version; otherwise 'false'. * @param version Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_operating_system_at_least_version(const OperatingSystemVersion& version) const; /** * @brief Calls `-[NSProcessInfo performActivityWithOptions:reason:usingBlock:]`. - * @details Synchronously performs an activity defined by a given block using the given options. The activity will be automatically ended after 'block' returns. - Parameters: - options: Options for the activity. See ''ProcessInfo/ActivityOptions'' for possible values. - reason: A string used in debugging to indicate the reason the activity began. - block: A block containing the work to be performed by the activity. + * @details Synchronously perform an activity. The activity will be automatically ended after your block argument returns. The reason string is used for debugging. * @param options Argument converted to the Objective-C parameter of the same role. * @param reason Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. @@ -95,139 +91,119 @@ namespace cocoon void perform_activity_with_options(ActivityOptions options, const std::string& reason, std::function block) const; /** * @brief Returns the `activeProcessorCount` property of `NSProcessInfo`. - * @details The number of active processing cores available on the computer. Whereas the ''processorCount'' property reports the number of advertised processing cores, the ''activeProcessorCount'' property reflects the actual number of active processing cores on the system. There are a number of different factors that may cause a core to not be active, including boot arguments, thermal throttling, or a manufacturing defect. This property value is equal to the result of entering the command 'sysctl -n hw.logicalcpu' on the current system. * @return The converted Objective-C result. */ std::uint64_t active_processor_count() const; /** * @brief Returns the `arguments` property of `NSProcessInfo`. - * @details Array of strings with the command-line arguments for the process. This array contains all the information passed in the 'argv' array, including the executable name in the first element. * @return The converted Objective-C result. */ std::vector arguments() const; /** * @brief Returns the `automaticTerminationSupportEnabled` property of `NSProcessInfo`. - * @details A Boolean value indicating whether the app supports automatic termination. Without setting this property or setting the equivalent 'Info.plist' key ('NSSupportsAutomaticTermination'), the methods ''disableAutomaticTermination:'' and ''enableAutomaticTermination:'' have no effect, although the counter tracking automatic termination opt-outs is still kept up to date to ensure correctness if this is called later. Currently, setting this property to 'NO' has no effect. This property should be set during '-applicationDidFinishLaunching:' or earlier. + * @details Marks the calling app as supporting automatic termination. Without calling this or setting the equivalent Info.plist key (NSSupportsAutomaticTermination), the above methods (disableAutomaticTermination:/enableAutomaticTermination:) have no effect, although the counter tracking automatic termination opt-outs is still kept up to date to ensure correctness if this is called later. Currently, passing NO has no effect. This should be called during -applicationDidFinishLaunching or earlier. * @return The converted Objective-C result. */ bool automatic_termination_support_enabled() const; /** * @brief Sets the `automaticTerminationSupportEnabled` property of `NSProcessInfo`. - * @details A Boolean value indicating whether the app supports automatic termination. Without setting this property or setting the equivalent 'Info.plist' key ('NSSupportsAutomaticTermination'), the methods ''disableAutomaticTermination:'' and ''enableAutomaticTermination:'' have no effect, although the counter tracking automatic termination opt-outs is still kept up to date to ensure correctness if this is called later. Currently, setting this property to 'NO' has no effect. This property should be set during '-applicationDidFinishLaunching:' or earlier. + * @details Marks the calling app as supporting automatic termination. Without calling this or setting the equivalent Info.plist key (NSSupportsAutomaticTermination), the above methods (disableAutomaticTermination:/enableAutomaticTermination:) have no effect, although the counter tracking automatic termination opt-outs is still kept up to date to ensure correctness if this is called later. Currently, passing NO has no effect. This should be called during -applicationDidFinishLaunching or earlier. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_automatic_termination_support_enabled(bool value) const; /** * @brief Returns the `environment` property of `NSProcessInfo`. - * @details The variable names (keys) and their values in the environment from which the process was launched. * @return The converted Objective-C result. */ std::map environment() const; /** * @brief Returns the `fullUserName` property of `NSProcessInfo`. - * @details Returns the full name of the current user. * @return The converted Objective-C result. */ std::string full_user_name() const; /** * @brief Returns the `globallyUniqueString` property of `NSProcessInfo`. - * @details Global unique identifier for the process. The global ID for the process includes the host name, process ID, and a time stamp, which ensures that the ID is unique for the network. This property generates a new string each time its getter is invoked, and it uses a counter to guarantee that strings created from the same process are unique. * @return The converted Objective-C result. */ std::string globally_unique_string() const; /** * @brief Returns the `hostName` property of `NSProcessInfo`. - * @details The name of the host computer on which the process is executing. * @return The converted Objective-C result. */ std::string host_name() const; /** * @brief Returns the `iOSAppOnMac` property of `NSProcessInfo`. - * @details A Boolean value that indicates whether the process is an iPhone or iPad app running on a Mac. The value of this property is 'YES' only when the process is an iOS app running on a Mac. The value is 'NO' for all other apps on the Mac, including Mac apps built using Mac Catalyst. The property is also 'NO' for processes running on platforms other than macOS. * @return The converted Objective-C result. */ bool isi_os_app_on_mac() const; /** * @brief Returns the `iOSAppOnVision` property of `NSProcessInfo`. - * @details A Boolean value that indicates whether the process is an iPhone or iPad app running on visionOS. The value of this property is 'YES' only when the process is an iOS app running on a visionOS device. The value is 'NO' for all other apps on visionOS. The property is also 'NO' for processes running on platforms other than visionOS. * @return The converted Objective-C result. */ bool isi_os_app_on_vision() const; /** * @brief Returns the `lowPowerModeEnabled` property of `NSProcessInfo`. - * @details A Boolean value that indicates the current state of Low Power Mode. Users who wish to prolong their device's battery life can enable Low Power Mode under Settings > Battery. In Low Power Mode, the system conserves battery life by enacting certain energy-saving measures, such as: - Reducing CPU and GPU performance. - Reducing screen brightness. - Pausing discretionary and background activities. Your app can query the 'isLowPowerModeEnabled' property at any time to determine whether Low Power Mode is active. Your app can also register to receive notifications when the Low Power Mode state of a device changes by observing ''NSProcessInfoPowerStateDidChangeNotification''. * @return The converted Objective-C result. */ bool is_low_power_mode_enabled() const; /** * @brief Returns the `macCatalystApp` property of `NSProcessInfo`. - * @details A Boolean value that indicates whether the process originated as an iOS app and runs on macOS. The value of this property is 'YES' when the process is a Mac app built with Mac Catalyst, or an iOS app running on Apple silicon, and is running on a Mac. Frameworks that support iOS and macOS use this property to determine if the process is a Mac app built with Mac Catalyst. > Note: > To distinguish between an iOS app running on Apple silicon and a Mac app built with Mac Catalyst, use the ''isiOSAppOnMac'' property. * @return The converted Objective-C result. */ bool is_mac_catalyst_app() const; /** * @brief Returns the `operatingSystemVersion` property of `NSProcessInfo`. - * @details The version of the operating system on which the process is executing. * @return The converted Objective-C result. */ OperatingSystemVersion operating_system_version() const; /** * @brief Returns the `operatingSystemVersionString` property of `NSProcessInfo`. - * @details A string containing the version of the operating system on which the process is executing. The operating system version string is human readable, localized, and is appropriate for displaying to the user. This string is not appropriate for parsing. + * @details Human readable, localized; appropriate for displaying to user or using in bug emails and such; NOT appropriate for parsing * @return The converted Objective-C result. */ std::string operating_system_version_string() const; /** * @brief Returns the `physicalMemory` property of `NSProcessInfo`. - * @details The amount of physical memory on the computer in bytes. * @return The converted Objective-C result. */ std::uint64_t physical_memory() const; /** * @brief Returns the `processIdentifier` property of `NSProcessInfo`. - * @details The identifier of the process (often called process ID). * @return The converted Objective-C result. */ int process_identifier() const; /** * @brief Returns the `processInfo` property of `NSProcessInfo`. - * @details Returns the process information agent for the process. An 'NSProcessInfo' object is created the first time this property is accessed, and that same object is returned on each subsequent access. * @return The converted Objective-C result. */ static ProcessInfo process_info(); /** * @brief Returns the `processName` property of `NSProcessInfo`. - * @details The name of the process. The process name is used to register application defaults and is used in error messages. It does not uniquely identify the process. > Warning: > User defaults and other aspects of the environment might depend on the process name, so be very careful if you change it. Setting the process name in this manner is not thread safe. * @return The converted Objective-C result. */ std::string process_name() const; /** * @brief Sets the `processName` property of `NSProcessInfo`. - * @details The name of the process. The process name is used to register application defaults and is used in error messages. It does not uniquely identify the process. > Warning: > User defaults and other aspects of the environment might depend on the process name, so be very careful if you change it. Setting the process name in this manner is not thread safe. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_process_name(const std::string& value) const; /** * @brief Returns the `processorCount` property of `NSProcessInfo`. - * @details The number of processing cores available on the computer. This property value is equal to the result of entering the command 'sysctl -n hw.ncpu' on the current system. * @return The converted Objective-C result. */ std::uint64_t processor_count() const; /** * @brief Returns the `systemUptime` property of `NSProcessInfo`. - * @details The amount of time the system has been awake since the last time it was restarted. > Important: > This API has the potential of being misused to access device signals to try to identify the device or user, also known as fingerprinting. Regardless of whether a user gives your app permission to track, fingerprinting is not allowed. When you use this API in your app or third-party SDK (an SDK not provided by Apple), declare your usage and the reason for using the API in your app or third-party SDK's 'PrivacyInfo.xcprivacy' file. For more information, including the list of valid reasons for using the API, see [Describing use of required reason API](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api). * @return The converted Objective-C result. */ double system_uptime() const; /** * @brief Returns the `thermalState` property of `NSProcessInfo`. - * @details The current thermal state of the system. At higher thermal states your app should reduce usage of system resources. For more information, see ''NSProcessInfoThermalState''. * @return The converted Objective-C result. */ ProcessInfoThermalState thermal_state() const; /** * @brief Returns the `userName` property of `NSProcessInfo`. - * @details Returns the account name of the current user. * @return The converted Objective-C result. */ std::string user_name() const; diff --git a/include/generated/progress.h b/include/generated/progress.h index 53b78db7..939f5a0f 100644 --- a/include/generated/progress.h +++ b/include/generated/progress.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSProgress` (Foundation). - * @details An object that conveys ongoing progress to the user for a specified task. The ''Progress'' class provides a self-contained mechanism for progress reporting. It makes it easy for code that performs work to report the progress of that work, and for user interface code to observe that progress for presentation to the user. Specifically, you can use a progress object to show the user a progress bar and explanatory text that update as you do work. It also allows the user to cancel or pause work. \#\#\# Reporting Progress Using the methods of this class, your code can report the progress it's currently making toward completing a task, including progress in related subtasks. You can create instances of this class using the ''init(parent:userInfo:)'' instance method or the ''init(totalUnitCount:)'' class method. Progress objects have many properties that you can use to observe and report current progress. For instance, the ''totalUnitCount'' property represents the total number of units of work, and the ''completedUnitCount'' and ''fractionCompleted'' properties represent how much of that work is complete. The ''fractionCompleted'' property is useful for updating progress indicators or textual descriptors. To check whether progress is complete, test the ''isFinished'' property. The following code shows a sample method that reports the progress of performing an operation on a piece of data. When creating the progress object, you set the value of its ''totalUnitCount'' property to a suitable batch size for the operation, and the ''completedUnitCount'' count is '0'. Each time the loop executes and processes a batch of data, you increment the progress object's ''completedUnitCount'' property appropriately. '''objc - (void)startTaskWithData:(NSData )data { NSUInteger batchSize = ... use a suitable batch size NSProgress progress = [NSProgress progressWithTotalUnitCount:batchSize]; for (NSUInteger index = 0; index \< batchSize; index++) { // Check for cancellation. if ([progress isCancelled]) { // Tidy up as necessary. break; } // Do something with this batch of data. // Report progress (add 1 because the work is complete for the current index). [progress setCompletedUnitCount:(index + 1)]; } } ''' Each of the properties of a progress object, including ''totalUnitCount'', ''completedUnitCount'', and ''fractionCompleted'', support key-value observing (KVO). This makes it extremely easy for a view or window controller object to observe the properties, and update UI elements, such as progress indicators, when the values change. It also means that there is a nonzero cost to updating the values of those properties, so avoid using a unit count that is too granular. If you're iterating over a large dataset, for example, and each operation takes only a trivial amount of time, divide the work into batches so you can update the unit count once per batch rather than once per iteration. \#\#\# Reporting Progress for Multiple Operations Sometimes, your code may need to report the overall progress of an operation that consists of several suboperations. To accomplish this, your code can report the progress of each suboperation by building up a tree of progress objects. The ''Progress'' reporting mechanism supports a loosely coupled relationship between progress objects. Suboperations don't need to know anything about the containing progress item — you can create new progress objects as suboperations of another progress instance. When you assign a progress instance, the system allocates a portion of the containing progress instance's pending unit count. When the suboperation's progress object completes, the containing progress object's ''completedUnitCount'' property automatically increases by a predefined amount. > Note: > The ''completedUnitCount'' property for a containing progress object only updates when the suboperation is '100\%' complete. The ''fractionCompleted'' property for a containing progress object updates continuously as work progresses for all suboperations. You add suboperation progress objects to your tree implicitly or explicitly. \#\#\#\# Adding a Progress Operation Implicitly Add a suboperation implicitly by setting a pending unit count for the containing progress object and creating a new ''Progress'' instance. When you create the new progress instance, the system sets it as a suboperation of the containing progress object, and assigns the pending unit count. As an example, consider that you're tracking the progress of code downloading and copying files on disk. You can use a single progress object to track the entire task, but it's easier to manage each subtask using a separate progress object. You start by creating an overall progress object with a suitable total unit count, call ''becomeCurrent(withPendingUnitCount:)'', then create your suboperation progress objects before finally calling ''resignCurrent()''. The system divides the pending unit count that you specify in the first method equally among the suboperation progress objects you create between these two method calls. Each suboperation progress object maintains its own internal unit count. When the suboperation object's ''completedUnitCount'' equals or exceeds its ''totalUnitCount'', the system increases the containing progress object's ''completedUnitCount'' by the assigned portion of the original pending unit count. In the following example, the overall progress object has 100 units. The two suboperation objects, therefore, get 50 pending units each, and keep track internally of 10 units of work each. When each suboperation completes its 10 units, the system increases the overall progress object's completed unit count by 50. '''objc - (void)startLongOperation { self.overallProgress = [NSProgress progressWithTotalUnitCount:100]; [self.overallProgress becomeCurrentWithPendingUnitCount:50]; [self work1]; [self.overallProgress resignCurrent]; [self.overallProgress becomeCurrentWithPendingUnitCount:50]; [self work2]; [self.overallProgress resignCurrent]; } - (void)work1 { NSProgress firstTaskProgress = [NSProgress progressWithTotalUnitCount:10]; // Perform first task. } - (void)work2 { NSProgress secondTaskProgress = [NSProgress progressWithTotalUnitCount:10]; // Perform second task. } ''' If you don't create any suboperation progress objects between the calls to ''becomeCurrent(withPendingUnitCount:)'' and ''resignCurrent()'', the containing progress object automatically updates its ''completedUnitCount'' by adding the pending units. \#\#\#\# Adding a Progress Operation Explicitly To add a progress operation explicitly, call ''addChild(:withPendingUnitCount:)'' on the containing progress object. The value for the pending unit count is the amount of the containing progress object's ''totalUnitCount'' that the suboperation consumes, which conforms to the ''ProgressReporting'' protocol. In the following example, the overall progress object has 10 units. The suboperation progress for the download gets eight units and tracks the download of a photo. The progress for the filter takes a lot less time and gets the remaining two units. When the download completes, the system updates the containing progress object's completed unit count by eight. When the filter completes, the system updates it by the remaining two units. '''objc - (void)startLongOperation { self.overallProgress = [NSProgress progressWithTotalUnitCount:10]; [self.overallProgress addChild:download.progress withPendingUnitCount:8]; // Do the download. [self.overallProgress addChild:filter.progress withPendingUnitCount:2]; // Perform the filter. } ''' + * @details NSProgress is used to report the amount of work done, and provides a way to allow the user to cancel that work. Since work is often split up into several parts, progress objects can form a tree where children represent part of the overall total work. Each parent may have as many children as required, but each child only has one parent. The top level progress object in this tree is typically the one that you would display to a user. The leaf objects are updated as work completes, and the updates propagate up the tree. The work that an NSProgress does is tracked via a "unit count." There are two unit count values: total and completed. In its leaf form, an NSProgress is created with a total unit count and its completed unit count is updated with -setCompletedUnitCount: until it matches the total unit count. The progress is then considered finished. When progress objects form nodes in trees, they are still created with a total unit count. Portions of the total are then handed out to children as a "pending unit count." The total amount handed out to children should add up to the parent's totalUnitCount. When those children become finished, the pending unit count assigned to that child is added to the parent's completedUnitCount. Therefore, when all children are finished, the parent's completedUnitCount is equal to its totalUnitCount and it becomes finished itself. Children NSProgress objects can be added implicitly or by invoking the -addChild:withPendingUnitCount: method on the parent. Implicitly added children are attached to a parent progress between a call to -becomeCurrentWithPendingUnitCount: and a call to -resignCurrent. The implicit child is created with the +progressWithTotalUnitCount: method or by passing the result of +currentProgress to the -initWithParent:userInfo: method. Both kinds of children can be attached to the same parent progress object. If you have an idea in advance that some portions of the work will take more or less time than the others, you can use different values of pending unit count for each child. If you are designing an interface of an object that reports progress, then the recommended approach is to vend an NSProgress property and adopt the NSProgressReporting protocol. The progress should be created with the -discreteProgressWithTotalUnitCount: method. You can then either update the progress object directly or set it to have children of its own. Users of your object can compose your progress into their tree by using the -addChild:withPendingUnitCount: method. If you want to provide progress reporting for a single method, then the recommended approach is to implicitly attach to a current NSProgress by creating an NSProgress object at the very beginning of your method using +progressWithTotalUnitCount:. This progress object will consume the pending unit count, and then you can set up the progress object with children of its own. The localizedDescription and localizedAdditionalDescription properties are meant to be observed as well as set. So are the cancellable and pausable properties. totalUnitCount and completedUnitCount on the other hand are often not the best properties to observe when presenting progress to the user. For example, you should observe fractionCompleted instead of observing totalUnitCount and completedUnitCount and doing your own calculation. NSProgress' default implementation of fractionCompleted does fairly sophisticated things like taking child NSProgresses into account. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -59,14 +59,14 @@ namespace cocoon explicit Progress(Adopt adopt); /** * @brief Calls `-[NSProgress addChild:withPendingUnitCount:]`. - * @details Adds a process object as a suboperation of a progress tree. - Parameters: - child: The progress instance to add to the progress tree. - inUnitCount: The number of units of work for the new suboperation to complete. You assign the suboperation a portion of the receiver's total unit count according to 'inUnitCount'. + * @details Directly add a child progress to the receiver, assigning it a portion of the receiver's total unit count. * @param child Argument converted to the Objective-C parameter of the same role. * @param in_unit_count Argument converted to the Objective-C parameter of the same role. */ void add_child(const Progress& child, std::int64_t in_unit_count) const; /** * @brief Calls `+[NSProgress addSubscriberForFileURL:withPublishingHandler:]`. - * @details Registers a file URL to hear about the progress of a file operation. - Parameters: - url: The URL of the file to observe. - publishingHandler: A closure that the system invokes when a progress object that represents a file operation matching the specified URL calls '-publish'. - Returns: A proxy of the progress object to observe. The system invokes the passed-in block when a progress object calls '-publish' with an 'NSProgressFileURLKey' user info dictionary entry that's a URL that is the same as this method's URL, or that is an item that the URL directly contains. The progress object that passes to your block is a proxy of the published progress object. The passed-in block may return another block. If it does, the system invokes the returned block when the observed progress object invokes '-unpublish', the publishing process terminates, or you invoke '+removeSubscriber:'. The system invokes the blocks you provide on the main thread. + * @details Register to hear about file progress. The passed-in block will be invoked when -publish has been sent to an NSProgress whose NSProgressFileURLKey user info dictionary entry is an NSURL locating the same item located by the passed-in NSURL, or an item directly contained by it. The NSProgress passed to your block will be a proxy of the one that was published. The passed-in block may return another block. If it does, then that returned block will be invoked when the corresponding invocation of -unpublish is made, or the publishing process terminates, or +removeSubscriber: is invoked. Your blocks will be invoked on the main thread. * @param url Argument converted to the Objective-C parameter of the same role. * @param publishing_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -74,304 +74,299 @@ namespace cocoon static Object add_subscriber_for_file_url(const URL& url, std::function(Progress)> publishing_handler); /** * @brief Calls `-[NSProgress becomeCurrentWithPendingUnitCount:]`. - * @details Sets the progress object as the current object of the current thread, and assigns the amount of work for the next suboperation progress object to perform. - Parameter unitCount: The number of units of work for the next progress object that initializes when you invoke '-initWithParent:userInfo:' in the current thread with this progress object as the containing progress object. The number represents the portion of work to perform in relation to the total number of units of work, which is the value of the progress object's 'totalUnitCount' property. The units of work for this parameter must be the same units of work in the progress object's 'totalUnitCount' property. Use this method to build a tree of progress objects. You must always balance invocations of this method with invocations of '-resignCurrent'. + * @details Make the receiver the current thread's current progress object, returned by +currentProgress. At the same time, record how large a portion of the work represented by the receiver will be represented by the next progress object initialized by invoking -initWithParent:userInfo: in the current thread with the receiver as the parent. This will be used when that child is sent -setCompletedUnitCount: and the receiver is notified of that. With this mechanism, code that doesn't know anything about its callers can report progress accurately by using +progressWithTotalUnitCount: and -setCompletedUnitCount:. The calling code will account for the fact that the work done is only a portion of the work to be done as part of a larger operation. The unit of work in a call to -becomeCurrentWithPendingUnitCount: has to be the same unit of work as that used for the value of the totalUnitCount property, but the unit of work used by the child can be a completely different one, and often will be. You must always balance invocations of this method with invocations of -resignCurrent. * @param unit_count Argument converted to the Objective-C parameter of the same role. */ void become_current_with_pending_unit_count(std::int64_t unit_count) const; /** * @brief Calls `-[NSProgress cancel]`. - * @details Cancels progress tracking. This method invokes the block for 'cancellationHandler', if there is one, and ensures that any subsequent reads of the 'isCancelled' property return 'YES'. If the receiver has suboperations, the system cancels their progress as well. + * @details Invoke the block registered with the cancellationHandler property, if there is one, and set the cancelled property to YES. Do this for the receiver, any descendants of the receiver, the instance of NSProgress that was published in another process to make the receiver if that's the case, and any descendants of such a published instance of NSProgress. */ void cancel() const; /** * @brief Calls `+[NSProgress currentProgress]`. - * @details Returns the progress instance, if any, associated with the current thread. If you invoke '-becomeCurrentWithPendingUnitCount:' on the current thread, this method returns the progress instance. Use this per-thread value to allow code that performs work to report useful progress even when it's widely separated from the code that actually presents progress information to the user, and without requiring layers of intervening code to pass around an 'NSProgress' instance. To ensure that you report progress in known units of work, you typically work with a suboperation progress object that you create by calling '+progressWithTotalUnitCount:'. + * @details The instance of NSProgress associated with the current thread by a previous invocation of -becomeCurrentWithPendingUnitCount:, if any. The purpose of this per-thread value is to allow code that does work to usefully report progress even when it is widely separated from the code that actually presents progress to the user, without requiring layers of intervening code to pass the instance of NSProgress through. Using the result of invoking this directly will often not be the right thing to do, because the invoking code will often not even know what units of work the current progress object deals in. Invoking +progressWithTotalUnitCount: to create a child NSProgress object and then using that to report progress makes more sense in that situation. * @return The converted Objective-C result. */ static Progress current_progress(); /** * @brief Calls `+[NSProgress discreteProgressWithTotalUnitCount:]`. - * @details Creates and returns a progress instance with the specified unit count that isn't part of any existing progress tree. - Parameter unitCount: The total number of units of work to assign to the progress instance. - Returns: A new progress instance with its containing progress object set to 'nil'. Use this method to create the top-level progress object that your custom classes return. The receiver of the returned progress object can add it to a progress tree using '-addChild:withPendingUnitCount:'. You're responsible for updating the progress count of the created progress object. You can invoke this method on one thread and then message the returned 'NSProgress' on another thread. For example, you can capture the created progress instance in a block that you pass to 'dispatch_async()'. In that block, you can invoke methods like '-becomeCurrentWithPendingUnitCount:' or '-resignCurrent', and set the 'completedUnitCount' or 'isCancelled' properties as your app finishes its work. + * @details Return an instance of NSProgress that has been initialized with -initWithParent:userInfo:. The initializer is passed nil for the parent, resulting in a progress object that is not part of an existing progress tree. The value of the totalUnitCount property is also set. * @param unit_count Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Progress discrete_progress_with_total_unit_count(std::int64_t unit_count); /** * @brief Calls `-[NSProgress pause]`. - * @details Pauses progress tracking. This method invokes the block for 'pausingHandler', if there is one, and ensures that any subsequent reads of the 'isPaused' property return 'YES'. If the receiver has suboperations, the system pauses their progress as well. + * @details Invoke the block registered with the pausingHandler property, if there is one, and set the paused property to YES. Do this for the receiver, any descendants of the receiver, the instance of NSProgress that was published in another process to make the receiver if that's the case, and any descendants of such a published instance of NSProgress. */ void pause() const; /** * @brief Calls `-[NSProgress performAsCurrentWithPendingUnitCount:usingBlock:]`. - * @details Retrieves the current thread's progress object, executes the specified block, and increments the progress object by the specified units of work. - Parameters: - unitCount: The number of units of work to increment for the current progress object. - work: A block that wraps the work you specify to complete for incrementing the current progress. Use this function as a convenience method to wrap an existing method or block to increment the current progress object. This function is the same as calling '-becomeCurrentWithPendingUnitCount:', doing the work you specify in the block, and calling '-resignCurrent'. + * @details Become current, do some work, then resign current. * @param unit_count Argument converted to the Objective-C parameter of the same role. * @param work Argument converted to the Objective-C parameter of the same role. */ void perform_as_current_with_pending_unit_count(std::int64_t unit_count, std::function work) const; /** * @brief Calls `-[NSProgress publish]`. - * @details Publishes the progress object for other processes to observe it. Entries in the user info dictionary determine whether another process can discover the progress object to observe it, and how it does that. For example, an 'NSProgressFileURLKey' entry makes a progress object discoverable by corresponding invokers of '+addSubscriberForFileURL:withPublishingHandler:'. When you make a progress object observable by other processes, you must ensure that at least 'localizedDescription', 'isIndeterminate', and 'fractionCompleted' always work when you send proxies of your progress object in other processes. You make 'isIndeterminate' and 'fractionCompleted' work by accurately setting the total and completed unit counts of the progress. You make 'localizedDescription' work by setting the value of the kind property to something valid, like 'NSProgressKindFile', and then fulfilling the requirements for that kind of progress. You can publish an instance of 'NSProgress' one time only. + * @details Make the NSProgress observable by other processes. Whether or not another process can discover the NSProgress to observe it, and how it would do that, depends on entries in the user info dictionary. For example, an NSProgressFileURLKey entry makes an NSProgress discoverable by corresponding invokers of +addSubscriberForFileURL:withPublishingHandler:. When you make an NSProgress observable by other processes you must ensure that at least -localizedDescription, -isIndeterminate, and -fractionCompleted always work when sent to proxies of your NSProgress in other processes. You make -isIndeterminate and -fractionCompleted always work by accurately setting the total and completed unit counts of the progress. You make -localizedDescription always work by setting the value of the kind property to something valid, like NSProgressKindFile, and then fulfilling the requirements for that specific kind of progress. (You can instead set the value of localizedDescription directly but that is not perfectly reliable because other processes might be using different localization languages than yours.) You can publish an instance of NSProgress at most once. */ void publish() const; /** * @brief Calls `+[NSProgress removeSubscriber:]`. - * @details Removes a proxy progress object that the add subscriber method returns. - Parameter subscriber: The proxy of the progress object to observe. If the block for '+addSubscriberForFileURL:withPublishingHandler:' returns a closure, the system invokes that closure on the main thread when you invoke '+removeSubscriber:'. + * @details Given the object returned by a previous invocation of -addSubscriberForFileURL:withPublishingHandler:, deregister. * @param subscriber Argument converted to the Objective-C parameter of the same role. */ static void remove_subscriber(const Object& subscriber); /** * @brief Calls `-[NSProgress resignCurrent]`. - * @details Restores the previous progress object to become the current progress object on the thread. This method restores the current progress object to what it was before invoking '-becomeCurrentWithPendingUnitCount:'. + * @details Balance the most recent previous invocation of -becomeCurrentWithPendingUnitCount: on the same thread by restoring the current progress object to what it was before -becomeCurrentWithPendingUnitCount: was invoked. */ void resign_current() const; /** * @brief Calls `-[NSProgress resume]`. - * @details Resumes progress tracking. This method invokes the block for 'resumingHandler', if there is one, and ensures that any subsequent reads of the 'isPaused' property return 'NO'. If the receiver has suboperations, the system resumes their progress as well. + * @details Invoke the block registered with the resumingHandler property, if there is one, and set the paused property to NO. Do this for the receiver, any descendants of the receiver, the instance of NSProgress that was published in another process to make the receiver if that's the case, and any descendants of such a published instance of NSProgress. */ void resume() const; /** * @brief Calls `-[NSProgress setUserInfoObject:forKey:]`. - * @details Sets a value in the user info dictionary. - Parameters: - objectOrNil: The object to set for the specified key, or 'nil' to remove an existing entry in the dictionary. - key: The key for storing the specified object. Use this method to set a value in the 'userInfo' dictionary, with appropriate KVO notification for properties with values that can depend on values in the user info dictionary, like 'localizedDescription'. + * @details Set a value in the dictionary returned by invocations of -userInfo, with appropriate KVO notification for properties whose values can depend on values in the user info dictionary, like localizedDescription. If a nil value is passed then the dictionary entry is removed. * @param object_or_nil Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void set_user_info_object(const Object& object_or_nil, const std::string& key) const; /** * @brief Calls `-[NSProgress unpublish]`. - * @details Removes a progress object from publication, making it unobservable by other processes. + * @details Make the NSProgress no longer observable by other processes. */ void unpublish() const; /** * @brief Returns the `cancellable` property of `NSProgress`. - * @details A Boolean value that indicates whether the receiver is tracking work that you can cancel. By default, 'NSProgress' objects are cancelable. You typically use this property to communicate whether controls for canceling appear in a progress-reporting user interface. 'NSProgress' itself doesn't do anything with this property other than help pass the value from progress reporters to progress observers. If an 'NSProgress' is cancelable, implement the ability to cancel progress either by setting a block for the 'cancellationHandler' property, or by polling the 'isCancelled' property periodically while performing the relevant work. It's valid for the value of this property to change during the lifetime of an 'NSProgress' object. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. + * @details Whether the work being done can be cancelled or paused, respectively. By default NSProgresses are cancellable but not pausable. NSProgress is by default KVO-compliant for these properties, with the notifications always being sent on the thread which updates the property. These properties are for communicating whether controls for cancelling and pausing should appear in a progress reporting user interface. NSProgress itself does not do anything with these properties other than help pass their values from progress reporters to progress observers. It is valid for the values of these properties to change in virtually any way during the lifetime of an NSProgress. Of course, if an NSProgress is cancellable you should actually implement cancellability by setting a cancellation handler or by making your code poll the result of invoking -isCancelled. Likewise for pausability. * @return The converted Objective-C result. */ bool is_cancellable() const; /** * @brief Sets the `cancellable` property of `NSProgress`. - * @details A Boolean value that indicates whether the receiver is tracking work that you can cancel. By default, 'NSProgress' objects are cancelable. You typically use this property to communicate whether controls for canceling appear in a progress-reporting user interface. 'NSProgress' itself doesn't do anything with this property other than help pass the value from progress reporters to progress observers. If an 'NSProgress' is cancelable, implement the ability to cancel progress either by setting a block for the 'cancellationHandler' property, or by polling the 'isCancelled' property periodically while performing the relevant work. It's valid for the value of this property to change during the lifetime of an 'NSProgress' object. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. + * @details Whether the work being done can be cancelled or paused, respectively. By default NSProgresses are cancellable but not pausable. NSProgress is by default KVO-compliant for these properties, with the notifications always being sent on the thread which updates the property. These properties are for communicating whether controls for cancelling and pausing should appear in a progress reporting user interface. NSProgress itself does not do anything with these properties other than help pass their values from progress reporters to progress observers. It is valid for the values of these properties to change in virtually any way during the lifetime of an NSProgress. Of course, if an NSProgress is cancellable you should actually implement cancellability by setting a cancellation handler or by making your code poll the result of invoking -isCancelled. Likewise for pausability. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_cancellable(bool value) const; /** * @brief Returns the `cancellationHandler` property of `NSProgress`. - * @details The block to invoke when canceling progress. If the receiver is a suboperation of another progress object, the system invokes the 'cancellationHandler' block when canceling the containing progress object. You're responsible for canceling any work for the progress object. You can invoke the cancellation handler on any queue. If you must do work on a specific queue, dispatch to that queue from within the cancellation handler block. + * @details A block to be invoked when cancel is invoked. The block will be invoked even when the method is invoked on an ancestor of the receiver, or an instance of NSProgress in another process that resulted from publishing the receiver or an ancestor of the receiver. Your block won't be invoked on any particular queue. If it must do work on a specific queue then it should schedule that work on that queue. * @return The converted Objective-C result. */ std::function cancellation_handler() const; /** * @brief Sets the `cancellationHandler` property of `NSProgress`. - * @details The block to invoke when canceling progress. If the receiver is a suboperation of another progress object, the system invokes the 'cancellationHandler' block when canceling the containing progress object. You're responsible for canceling any work for the progress object. You can invoke the cancellation handler on any queue. If you must do work on a specific queue, dispatch to that queue from within the cancellation handler block. + * @details A block to be invoked when cancel is invoked. The block will be invoked even when the method is invoked on an ancestor of the receiver, or an instance of NSProgress in another process that resulted from publishing the receiver or an ancestor of the receiver. Your block won't be invoked on any particular queue. If it must do work on a specific queue then it should schedule that work on that queue. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_cancellation_handler(std::function value) const; /** * @brief Returns the `cancelled` property of `NSProgress`. - * @details A Boolean value that indicates whether the receiver is tracking canceled work. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. If the receiver has a canceled containing progress object, the receiver reports a canceled status. + * @details Whether the work being done has been cancelled or paused, respectively. NSProgress is by default KVO-compliant for these properties, with the notifications always being sent on the thread which updates the property. Instances of NSProgress that have parents are at least as cancelled or paused as their parents. * @return The converted Objective-C result. */ bool is_cancelled() const; /** * @brief Returns the `completedUnitCount` property of `NSProgress`. - * @details The number of completed units of work for the current job. For an 'NSProgress' with a kind of 'NSProgressKindFile', the unit of this property is bytes, and the 'NSProgressFileTotalCountKey' and 'NSProgressFileCompletedCountKey' keys in the 'userInfo' dictionary report the overall count of files. For any other kind of 'NSProgress', the unit of measurement doesn't matter as long as it's consistent. You can report the values to the user in the 'localizedDescription' and 'localizedAdditionalDescription'. * @return The converted Objective-C result. */ std::int64_t completed_unit_count() const; /** * @brief Sets the `completedUnitCount` property of `NSProgress`. - * @details The number of completed units of work for the current job. For an 'NSProgress' with a kind of 'NSProgressKindFile', the unit of this property is bytes, and the 'NSProgressFileTotalCountKey' and 'NSProgressFileCompletedCountKey' keys in the 'userInfo' dictionary report the overall count of files. For any other kind of 'NSProgress', the unit of measurement doesn't matter as long as it's consistent. You can report the values to the user in the 'localizedDescription' and 'localizedAdditionalDescription'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_completed_unit_count(std::int64_t value) const; /** * @brief Returns the `estimatedTimeRemaining` property of `NSProgress`. - * @details How much time is probably left in the operation, as an 'NSNumber' containing a number of seconds. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details How much time is probably left in the operation, as an NSNumber containing a number of seconds. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @return The converted Objective-C result. */ Number estimated_time_remaining() const; /** * @brief Sets the `estimatedTimeRemaining` property of `NSProgress`. - * @details How much time is probably left in the operation, as an 'NSNumber' containing a number of seconds. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details How much time is probably left in the operation, as an NSNumber containing a number of seconds. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_estimated_time_remaining(const Number& value) const; /** * @brief Returns the `fileCompletedCount` property of `NSProgress`. - * @details If the progress is operating on a set of files, the number of completed files in the operation. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details If the progress is operating on a set of files, then set to the number of completed files in the operation. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @return The converted Objective-C result. */ Number file_completed_count() const; /** * @brief Sets the `fileCompletedCount` property of `NSProgress`. - * @details If the progress is operating on a set of files, the number of completed files in the operation. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details If the progress is operating on a set of files, then set to the number of completed files in the operation. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_file_completed_count(const Number& value) const; /** * @brief Returns the `fileOperationKind` property of `NSProgress`. - * @details The kind of file operation for the progress object. Set this value when the 'kind' property is 'NSProgressKindFile' to describe the kind of file operation. If present, 'NSProgress' presents additional information in its localized description by setting a value in the 'userInfo' dictionary. + * @details When the kind property is NSProgressKindFile, this value should be set. It describes the kind of file operation being performed. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @return The converted Objective-C result. */ std::string file_operation_kind() const; /** * @brief Sets the `fileOperationKind` property of `NSProgress`. - * @details The kind of file operation for the progress object. Set this value when the 'kind' property is 'NSProgressKindFile' to describe the kind of file operation. If present, 'NSProgress' presents additional information in its localized description by setting a value in the 'userInfo' dictionary. + * @details When the kind property is NSProgressKindFile, this value should be set. It describes the kind of file operation being performed. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_file_operation_kind(const std::string& value) const; /** * @brief Returns the `fileTotalCount` property of `NSProgress`. - * @details If the progress is operating on a set of files, the total number of files in the operation. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details If the progress is operating on a set of files, then set to the total number of files in the operation. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @return The converted Objective-C result. */ Number file_total_count() const; /** * @brief Sets the `fileTotalCount` property of `NSProgress`. - * @details If the progress is operating on a set of files, the total number of files in the operation. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details If the progress is operating on a set of files, then set to the total number of files in the operation. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_file_total_count(const Number& value) const; /** * @brief Returns the `fileURL` property of `NSProgress`. - * @details A URL that represents the file for the current progress object. Set this value for a progress that you publish to subscribers that register for updates using '+addSubscriberForFileURL:withPublishingHandler:'. If present, 'NSProgress' presents additional information in its localized description by setting a value in the 'userInfo' dictionary. + * @details A URL identifying the item on which progress is being made. This is required for any NSProgress that is published using -publish to be reported to subscribers registered with +addSubscriberForFileURL:withPublishingHandler: If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @return The converted Objective-C result. */ URL file_url() const; /** * @brief Sets the `fileURL` property of `NSProgress`. - * @details A URL that represents the file for the current progress object. Set this value for a progress that you publish to subscribers that register for updates using '+addSubscriberForFileURL:withPublishingHandler:'. If present, 'NSProgress' presents additional information in its localized description by setting a value in the 'userInfo' dictionary. + * @details A URL identifying the item on which progress is being made. This is required for any NSProgress that is published using -publish to be reported to subscribers registered with +addSubscriberForFileURL:withPublishingHandler: If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_file_url(const URL& value) const; /** * @brief Returns the `finished` property of `NSProgress`. - * @details A Boolean value that indicates the progress object is complete. A progress object finishes when the 'completedUnitCount' equals or exceeds the 'totalUnitCount'. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. + * @details True if the progress is considered finished. This property is observable. * @return The converted Objective-C result. */ bool is_finished() const; /** * @brief Returns the `fractionCompleted` property of `NSProgress`. - * @details The fraction of the overall work completed by this progress object, including work done by any children it may have. If the receiver object doesn't have any suboperations, 'fractionCompleted' is generally the result of dividing 'completedUnitCount' by 'totalUnitCount'. Setting both 'totalUnitCount' and 'completedUnitCount' to zero indicates that there is no progress to track. In this case, 'isIndeterminate' returns 'NO' and 'fractionCompleted' returns '0.0'. If the receiver does have suboperations, 'fractionCompleted' reflects progress from those progress objects in addition to its own 'completedUnitCount'. When the suboperations finish, the 'completedUnitCount' of the containing progress object updates. + * @details The fraction of the overall work completed by this progress object, including work done by any children it may have. * @return The converted Objective-C result. */ double fraction_completed() const; /** * @brief Returns the `indeterminate` property of `NSProgress`. - * @details A Boolean value that indicates whether the tracked progress is indeterminate. Use indeterminate progress only when you're unable to determine a reasonable value for either 'completedUnitCount' or 'totalUnitCount'. Progress is indeterminate when the value of the 'totalUnitCount' or 'completedUnitCount' is less than zero or if both values are zero. When progress is indeterminate, 'fractionCompleted' returns '0.0' and 'isFinished' returns 'NO'. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. + * @details Whether the progress being made is indeterminate. -isIndeterminate returns YES when the value of the totalUnitCount or completedUnitCount property is less than zero. Zero values for both of those properties indicates that there turned out to not be any work to do after all; -isIndeterminate returns NO and -fractionCompleted returns 1.0 in that case. NSProgress is by default KVO-compliant for these properties, with the notifications always being sent on the thread which updates the property. * @return The converted Objective-C result. */ bool is_indeterminate() const; /** * @brief Returns the `kind` property of `NSProgress`. - * @details An object that represents the kind of progress for the progress object. This property identifies the kind of progress for the progress object, such as 'NSProgressKindFile'. It can be 'nil'. If you set a non-'nil' value to 'kind', the default 'localizedDescription' getter uses the kind of progress to determine how to use the values of other properties, along with values in the user info dictionary, to create a string representation. + * @details Either a string identifying what kind of progress is being made, like NSProgressKindFile, or nil. If the value of the localizedDescription property has not been set to a non-nil value then the default implementation of -localizedDescription uses the progress kind to determine how to use the values of other properties, as well as values in the user info dictionary, to create a string that is presentable to the user. This is most useful when -localizedDescription is actually being invoked in another process, whose localization language may be different, as a result of using the publish and subscribe mechanism described here. * @return The converted Objective-C result. */ std::string kind() const; /** * @brief Sets the `kind` property of `NSProgress`. - * @details An object that represents the kind of progress for the progress object. This property identifies the kind of progress for the progress object, such as 'NSProgressKindFile'. It can be 'nil'. If you set a non-'nil' value to 'kind', the default 'localizedDescription' getter uses the kind of progress to determine how to use the values of other properties, along with values in the user info dictionary, to create a string representation. + * @details Either a string identifying what kind of progress is being made, like NSProgressKindFile, or nil. If the value of the localizedDescription property has not been set to a non-nil value then the default implementation of -localizedDescription uses the progress kind to determine how to use the values of other properties, as well as values in the user info dictionary, to create a string that is presentable to the user. This is most useful when -localizedDescription is actually being invoked in another process, whose localization language may be different, as a result of using the publish and subscribe mechanism described here. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_kind(const std::string& value) const; /** * @brief Returns the `localizedAdditionalDescription` property of `NSProgress`. - * @details A more specific localized description of tracked progress for the receiver. If you don't specify your own custom value for this property, 'NSProgress' uses the value of the 'kind' property to determine how to use the values of other properties, as well as values in the user info dictionary, to return an automatically computed string. If it fails to do that, it returns an empty string. The 'localizedAdditionalDescription' is more specific than 'localizedDescription' about the work the receiver is tracking at any particular moment. Depending on the kind of progress, the completed and total unit counts, and other parameters, localized additional descriptions resemble the following: - 3 of 10 files - 123 KB of 789.1 MB - 3.3 MB of 103.92 GB -- 2 hours remaining - 1.61 GB of 3.22 GB (2 KB/sec) -- 2 minutes remaining - 1 minute remaining (1 KB/sec) + * @details A more specific description of what progress is being made, fit to present to the user. NSProgress is by default KVO-compliant for this property, with the notifications always being sent on thread which updates the property. The default implementation of the getter for this property does not always return the most recently set value of the property. If the most recently set value of this property is nil then NSProgress uses the value of the kind property to determine how to use the values of other properties, as well as values in the user info dictionary, to return a computed string. If it fails to do that then it returns an empty string. The difference between this and localizedDescription is that this text is meant to be more specific about what work is being done at any particular moment. For example, depending on the kind of progress, the completed and total unit counts, and other parameters, these kinds of strings may be generated: 3 of 10 files 123 KB of 789.1 MB 3.3 MB of 103.92 GB — 2 minutes remaining 1.61 GB of 3.22 GB (2 KB/sec) — 2 minutes remaining 1 minute remaining (1 KB/sec) * @return The converted Objective-C result. */ std::string localized_additional_description() const; /** * @brief Sets the `localizedAdditionalDescription` property of `NSProgress`. - * @details A more specific localized description of tracked progress for the receiver. If you don't specify your own custom value for this property, 'NSProgress' uses the value of the 'kind' property to determine how to use the values of other properties, as well as values in the user info dictionary, to return an automatically computed string. If it fails to do that, it returns an empty string. The 'localizedAdditionalDescription' is more specific than 'localizedDescription' about the work the receiver is tracking at any particular moment. Depending on the kind of progress, the completed and total unit counts, and other parameters, localized additional descriptions resemble the following: - 3 of 10 files - 123 KB of 789.1 MB - 3.3 MB of 103.92 GB -- 2 hours remaining - 1.61 GB of 3.22 GB (2 KB/sec) -- 2 minutes remaining - 1 minute remaining (1 KB/sec) + * @details A more specific description of what progress is being made, fit to present to the user. NSProgress is by default KVO-compliant for this property, with the notifications always being sent on thread which updates the property. The default implementation of the getter for this property does not always return the most recently set value of the property. If the most recently set value of this property is nil then NSProgress uses the value of the kind property to determine how to use the values of other properties, as well as values in the user info dictionary, to return a computed string. If it fails to do that then it returns an empty string. The difference between this and localizedDescription is that this text is meant to be more specific about what work is being done at any particular moment. For example, depending on the kind of progress, the completed and total unit counts, and other parameters, these kinds of strings may be generated: 3 of 10 files 123 KB of 789.1 MB 3.3 MB of 103.92 GB — 2 minutes remaining 1.61 GB of 3.22 GB (2 KB/sec) — 2 minutes remaining 1 minute remaining (1 KB/sec) * @param value Argument converted to the Objective-C parameter of the same role. */ void set_localized_additional_description(const std::string& value) const; /** * @brief Returns the `localizedDescription` property of `NSProgress`. - * @details A localized description of tracked progress for the receiver. If you don't specify your own custom value for this property, 'NSProgress' uses the value of the 'kind' property to determine how to use the values of other properties, as well as values in the user info dictionary, to return an automatically computed string. If it fails to do that, it returns an empty string. The 'localizedDescription' represents a general description of the work the receiver tracks. Depending on the kind of progress, the completed and total unit counts, and other parameters, localized descriptions resemble the following: - Copying 10 files... - 30\% completed - Copying “TextEdit”... By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. + * @details A description of what progress is being made, fit to present to the user. NSProgress is by default KVO-compliant for this property, with the notifications always being sent on thread which updates the property. The default implementation of the getter for this property does not always return the most recently set value of the property. If the most recently set value of this property is nil then NSProgress uses the value of the kind property to determine how to use the values of other properties, as well as values in the user info dictionary, to return a computed string. If it fails to do that then it returns an empty string. For example, depending on the kind of progress, the completed and total unit counts, and other parameters, these kinds of strings may be generated: Copying 10 files… 30\% completed Copying “TextEdit”… * @return The converted Objective-C result. */ std::string localized_description() const; /** * @brief Sets the `localizedDescription` property of `NSProgress`. - * @details A localized description of tracked progress for the receiver. If you don't specify your own custom value for this property, 'NSProgress' uses the value of the 'kind' property to determine how to use the values of other properties, as well as values in the user info dictionary, to return an automatically computed string. If it fails to do that, it returns an empty string. The 'localizedDescription' represents a general description of the work the receiver tracks. Depending on the kind of progress, the completed and total unit counts, and other parameters, localized descriptions resemble the following: - Copying 10 files... - 30\% completed - Copying “TextEdit”... By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. + * @details A description of what progress is being made, fit to present to the user. NSProgress is by default KVO-compliant for this property, with the notifications always being sent on thread which updates the property. The default implementation of the getter for this property does not always return the most recently set value of the property. If the most recently set value of this property is nil then NSProgress uses the value of the kind property to determine how to use the values of other properties, as well as values in the user info dictionary, to return a computed string. If it fails to do that then it returns an empty string. For example, depending on the kind of progress, the completed and total unit counts, and other parameters, these kinds of strings may be generated: Copying 10 files… 30\% completed Copying “TextEdit”… * @param value Argument converted to the Objective-C parameter of the same role. */ void set_localized_description(const std::string& value) const; /** * @brief Returns the `old` property of `NSProgress`. - * @details A Boolean value that indicates when the observed progress object invokes the publish method before you subscribe to it. The publish and subscribe mechanism is generally level-triggered, in that when you invoke '+addSubscriberForFileURL:withPublishingHandler:', the system invokes your block for every relevant published and unpublished progress object. Sometimes you need to implement edge-triggered behavior, in which you do something either exactly when new progress begins or not at all. There's no reliable definition of before in this case, which involves multiple processes in a preemptively scheduled system. Don't use this method for anything more important than best efforts at animating. It can be inaccurate due to processes coming and going from unpredictable user actions. + * @details Return YES if the receiver represents progress that was published before the invocation of +addSubscriberForFileURL:withPublishingHandler: that resulted in the receiver appearing in this process, NO otherwise. The publish and subscribe mechanism described here is generally "level triggered," in that when you invoke +addSubscriberForFileURL:withPublishingHandler: your block will be invoked for every relevant NSProgress that has already been published and not yet unpublished. Sometimes however you need to implement "edge triggered" behavior, in which you do something either exactly when new progress begins or not at all. In the example described above, the Dock does not animate file icon flying when this method returns YES. Note that there is no reliable definition of "before" in this case, which involves multiple processes in a preemptively scheduled system. You should not use this method for anything more important than best efforts at animating perfectly in the face of processes coming and going due to unpredictable user actions. * @return The converted Objective-C result. */ bool is_old() const; /** * @brief Returns the `pausable` property of `NSProgress`. - * @details A Boolean value that indicates whether the receiver is tracking work that you can pause. By default, 'NSProgress' objects aren't pausable. You typically use this property to communicate whether controls for pausing appear in a progress-reporting user interface. 'NSProgress' itself doesn't do anything with this property other than help pass the value from progress reporters to progress observers. If an 'NSProgress' is pausable, implement the ability to pause either by setting a block for the 'pausingHandler' property, or by polling the 'isPaused' property periodically while performing the relevant work. It's valid for the value of this property to change during the lifetime of an 'NSProgress' object. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. * @return The converted Objective-C result. */ bool is_pausable() const; /** * @brief Sets the `pausable` property of `NSProgress`. - * @details A Boolean value that indicates whether the receiver is tracking work that you can pause. By default, 'NSProgress' objects aren't pausable. You typically use this property to communicate whether controls for pausing appear in a progress-reporting user interface. 'NSProgress' itself doesn't do anything with this property other than help pass the value from progress reporters to progress observers. If an 'NSProgress' is pausable, implement the ability to pause either by setting a block for the 'pausingHandler' property, or by polling the 'isPaused' property periodically while performing the relevant work. It's valid for the value of this property to change during the lifetime of an 'NSProgress' object. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_pausable(bool value) const; /** * @brief Returns the `paused` property of `NSProgress`. - * @details A Boolean value that indicates whether the receiver is tracking paused work. By default, 'NSProgress' is KVO-compliant for this property. It sends notifications on the same thread that updates the property. If the receiver has a paused containing progress object, the receiver reports a paused status. * @return The converted Objective-C result. */ bool is_paused() const; /** * @brief Returns the `pausingHandler` property of `NSProgress`. - * @details The block to invoke when pausing progress. If the receiver is a suboperation of another progress object, the system invokes the 'pausingHandler' block when pausing the containing progress object. You're responsible for pausing any work for the progress object. You can invoke the pausing handler on any queue. If you must do work on a specific queue, dispatch to that queue from within the pausing handler block. + * @details A block to be invoked when pause is invoked. The block will be invoked even when the method is invoked on an ancestor of the receiver, or an instance of NSProgress in another process that resulted from publishing the receiver or an ancestor of the receiver. Your block won't be invoked on any particular queue. If it must do work on a specific queue then it should schedule that work on that queue. * @return The converted Objective-C result. */ std::function pausing_handler() const; /** * @brief Sets the `pausingHandler` property of `NSProgress`. - * @details The block to invoke when pausing progress. If the receiver is a suboperation of another progress object, the system invokes the 'pausingHandler' block when pausing the containing progress object. You're responsible for pausing any work for the progress object. You can invoke the pausing handler on any queue. If you must do work on a specific queue, dispatch to that queue from within the pausing handler block. + * @details A block to be invoked when pause is invoked. The block will be invoked even when the method is invoked on an ancestor of the receiver, or an instance of NSProgress in another process that resulted from publishing the receiver or an ancestor of the receiver. Your block won't be invoked on any particular queue. If it must do work on a specific queue then it should schedule that work on that queue. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_pausing_handler(std::function value) const; /** * @brief Returns the `resumingHandler` property of `NSProgress`. - * @details The block to invoke when progress resumes. If the receiver is a suboperation of another progress object, the system invokes the 'resumingHandler' block when resuming the containing progress object. You're responsible for resuming any work for the progress object. You can invoke the resuming handler on any queue. If you must do work on a specific queue, dispatch to that queue from within the resuming handler block. + * @details A block to be invoked when resume is invoked. The block will be invoked even when the method is invoked on an ancestor of the receiver, or an instance of NSProgress in another process that resulted from publishing the receiver or an ancestor of the receiver. Your block won't be invoked on any particular queue. If it must do work on a specific queue then it should schedule that work on that queue. * @return The converted Objective-C result. */ std::function resuming_handler() const; /** * @brief Sets the `resumingHandler` property of `NSProgress`. - * @details The block to invoke when progress resumes. If the receiver is a suboperation of another progress object, the system invokes the 'resumingHandler' block when resuming the containing progress object. You're responsible for resuming any work for the progress object. You can invoke the resuming handler on any queue. If you must do work on a specific queue, dispatch to that queue from within the resuming handler block. + * @details A block to be invoked when resume is invoked. The block will be invoked even when the method is invoked on an ancestor of the receiver, or an instance of NSProgress in another process that resulted from publishing the receiver or an ancestor of the receiver. Your block won't be invoked on any particular queue. If it must do work on a specific queue then it should schedule that work on that queue. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_resuming_handler(std::function value) const; /** * @brief Returns the `throughput` property of `NSProgress`. - * @details How fast data is being processed, as an 'NSNumber' containing bytes per second. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details How fast data is being processed, as an NSNumber containing bytes per second. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @return The converted Objective-C result. */ Number throughput() const; /** * @brief Sets the `throughput` property of `NSProgress`. - * @details How fast data is being processed, as an 'NSNumber' containing bytes per second. This property is optional. If present, 'NSProgress' will use the information to present more information in its localized description. This property sets a value in the user info dictionary. + * @details How fast data is being processed, as an NSNumber containing bytes per second. This property is optional. If present, NSProgress will use the information to present more information in its localized description. This property sets a value in the userInfo dictionary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_throughput(const Number& value) const; /** * @brief Returns the `totalUnitCount` property of `NSProgress`. - * @details The total number of tracked units of work for the current progress. For an 'NSProgress' with a kind of 'NSProgressKindFile', the unit of this property is bytes, and the 'NSProgressFileTotalCountKey' and 'NSProgressFileCompletedCountKey' keys in the 'userInfo' dictionary report the overall count of files. For any other kind of 'NSProgress', the unit of measurement doesn't matter as long as it's consistent. You can report the values to the user in the 'localizedDescription' and 'localizedAdditionalDescription'. + * @details The size of the job whose progress is being reported, and how much of it has been completed so far, respectively. For an NSProgress with a kind of NSProgressKindFile, the unit of these properties is bytes while the NSProgressFileTotalCountKey and NSProgressFileCompletedCountKey keys in the userInfo dictionary are used for the overall count of files. For any other kind of NSProgress, the unit of measurement you use does not matter as long as you are consistent. The values may be reported to the user in the localizedDescription and localizedAdditionalDescription. If the receiver NSProgress object is a "leaf progress" (no children), then the fractionCompleted is generally completedUnitCount / totalUnitCount. If the receiver NSProgress has children, the fractionCompleted will reflect progress made in child objects in addition to its own completedUnitCount. As children finish, the completedUnitCount of the parent will be updated. * @return The converted Objective-C result. */ std::int64_t total_unit_count() const; /** * @brief Sets the `totalUnitCount` property of `NSProgress`. - * @details The total number of tracked units of work for the current progress. For an 'NSProgress' with a kind of 'NSProgressKindFile', the unit of this property is bytes, and the 'NSProgressFileTotalCountKey' and 'NSProgressFileCompletedCountKey' keys in the 'userInfo' dictionary report the overall count of files. For any other kind of 'NSProgress', the unit of measurement doesn't matter as long as it's consistent. You can report the values to the user in the 'localizedDescription' and 'localizedAdditionalDescription'. + * @details The size of the job whose progress is being reported, and how much of it has been completed so far, respectively. For an NSProgress with a kind of NSProgressKindFile, the unit of these properties is bytes while the NSProgressFileTotalCountKey and NSProgressFileCompletedCountKey keys in the userInfo dictionary are used for the overall count of files. For any other kind of NSProgress, the unit of measurement you use does not matter as long as you are consistent. The values may be reported to the user in the localizedDescription and localizedAdditionalDescription. If the receiver NSProgress object is a "leaf progress" (no children), then the fractionCompleted is generally completedUnitCount / totalUnitCount. If the receiver NSProgress has children, the fractionCompleted will reflect progress made in child objects in addition to its own completedUnitCount. As children finish, the completedUnitCount of the parent will be updated. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_total_unit_count(std::int64_t value) const; /** * @brief Returns the `userInfo` property of `NSProgress`. - * @details A dictionary of arbitrary values for the receiver. A KVO-compliant dictionary that changes in response to '-setUserInfoObject:forKey:'. The dictionary sends all of its KVO notifications on the thread that updates the property. Some entries have meanings that the 'NSProgress' class recognizes. See the 'NSProgress...Key' string constants listed below. + * @details Arbitrary values associated with the receiver. Returns a KVO-compliant dictionary that changes as -setUserInfoObject:forKey: is sent to the receiver. The dictionary will send all of its KVO notifications on the thread which updates the property. The result will never be nil, but may be an empty dictionary. Some entries have meanings that are recognized by the NSProgress class itself. See the NSProgress...Key string constants listed below. * @return The converted Objective-C result. */ std::map user_info() const; diff --git a/include/generated/property_list_serialization.h b/include/generated/property_list_serialization.h index acb8bc8b..2eff59f7 100644 --- a/include/generated/property_list_serialization.h +++ b/include/generated/property_list_serialization.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSPropertyListSerialization` (Foundation). - * @details An object that converts between a property list and one of several serialized representations. The ''PropertyListSerialization'' class provides methods that convert a property list to and from several serialized formats. A property list is itself an array or dictionary that contains only ''NSData'', ''NSString'', ''NSArray'', ''NSDictionary'', ''NSDate'', and ''NSNumber'' objects. Property list objects are toll-free bridged with their respective Core Foundation types (\, \, and so on). See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -35,7 +34,7 @@ namespace cocoon explicit PropertyListSerialization(Adopt adopt); /** * @brief Calls `+[NSPropertyListSerialization dataWithPropertyList:format:options:error:]`. - * @details Returns an 'NSData' object containing the serialized representation of a given property list in a given format. The format can be either 'NSPropertyListXMLFormat_v1_0' or 'NSPropertyListBinaryFormat_v1_0'. The 'opt' parameter is currently unused and should be set to '0'. If an error occurs the return value will be 'nil' and the error parameter (if non-NULL) set to an autoreleased 'NSError' describing the problem. + * @details Create an NSData from a property list. The format can be either NSPropertyListXMLFormat_v1_0 or NSPropertyListBinaryFormat_v1_0. The options parameter is currently unused and should be set to 0. If an error occurs the return value will be nil and the error parameter (if non-NULL) set to an autoreleased NSError describing the problem. * @param plist Argument converted to the Objective-C parameter of the same role. * @param format Argument converted to the Objective-C parameter of the same role. * @param opt Argument converted to the Objective-C parameter of the same role. @@ -44,7 +43,7 @@ namespace cocoon static std::vector data_with_property_list(const Object& plist, PropertyListFormat format, std::uint64_t opt); /** * @brief Calls `+[NSPropertyListSerialization propertyList:isValidForFormat:]`. - * @details Returns a Boolean value that indicates whether a given property list is valid for a given format. + * @details Verify that a specified property list is valid for a given format. Returns YES if the property list is valid. * @param plist Argument converted to the Objective-C parameter of the same role. * @param format Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -52,7 +51,7 @@ namespace cocoon static bool property_list(const Object& plist, PropertyListFormat format); /** * @brief Calls `+[NSPropertyListSerialization propertyListWithData:options:format:error:]`. - * @details Creates and returns a property list from the specified data. The options can be any of 'NSPropertyListMutabilityOptions'. If the format parameter is non-NULL, it will be filled out with the format that the property list was stored in. If an error occurs the return value will be 'nil' and the error parameter (if non-NULL) set to an autoreleased 'NSError' describing the problem. + * @details Create a property list from an NSData. The options can be any of NSPropertyListMutabilityOptions. If the format parameter is non-NULL, it will be filled out with the format that the property list was stored in. If an error occurs the return value will be nil and the error parameter (if non-NULL) set to an autoreleased NSError describing the problem. * @param data Argument converted to the Objective-C parameter of the same role. * @param opt Argument converted to the Objective-C parameter of the same role. * @param format Argument converted to the Objective-C parameter of the same role. @@ -61,7 +60,7 @@ namespace cocoon static Object property_list_with_data(const std::vector& data, PropertyListMutabilityOptions opt, PropertyListFormat* format); /** * @brief Calls `+[NSPropertyListSerialization propertyListWithStream:options:format:error:]`. - * @details Creates and returns a property list by reading from the specified stream. The options can be any of 'NSPropertyListMutabilityOptions'. If the format parameter is non-NULL, it will be filled out with the format that the property list was stored in. If an error occurs the return value will be 'nil' and the error parameter (if non-NULL) set to an autoreleased 'NSError' describing the problem. + * @details Create a property list by reading from an NSInputStream. The options can be any of NSPropertyListMutabilityOptions. If the format parameter is non-NULL, it will be filled out with the format that the property list was stored in. If an error occurs the return value will be nil and the error parameter (if non-NULL) set to an autoreleased NSError describing the problem. * @param stream Argument converted to the Objective-C parameter of the same role. * @param opt Argument converted to the Objective-C parameter of the same role. * @param format Argument converted to the Objective-C parameter of the same role. @@ -70,7 +69,7 @@ namespace cocoon static Object property_list_with_stream(const InputStream& stream, PropertyListMutabilityOptions opt, PropertyListFormat* format); /** * @brief Calls `+[NSPropertyListSerialization writePropertyList:toStream:format:options:error:]`. - * @details Writes a property list to an output stream in a given format. The stream should be opened and configured. The format can be either 'NSPropertyListXMLFormat_v1_0' or 'NSPropertyListBinaryFormat_v1_0'. The 'opt' parameter is currently unused and should be set to '0'. If an error occurs the return value will be '0' and the error parameter (if non-NULL) set to an autoreleased 'NSError' describing the problem. In a successful case, the return value is the number of bytes written to the stream. + * @details Write a property list to an output stream. The stream should be opened and configured. The format can be either NSPropertyListXMLFormat_v1_0 or NSPropertyListBinaryFormat_v1_0. The options parameter is currently unused and should be set to 0. If an error occurs the return value will be 0 and the error parameter (if non-NULL) set to an autoreleased NSError describing the problem. In a successful case, the return value is the number of bytes written to the stream. * @param plist Argument converted to the Objective-C parameter of the same role. * @param stream Argument converted to the Objective-C parameter of the same role. * @param format Argument converted to the Objective-C parameter of the same role. diff --git a/include/generated/purgeable_data.h b/include/generated/purgeable_data.h index 125607d9..027b1705 100644 --- a/include/generated/purgeable_data.h +++ b/include/generated/purgeable_data.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSPurgeableData` (Foundation). - * @details A mutable data object containing bytes that can be discarded when they're no longer needed. ''NSPurgeableData'' objects inherit their creation methods from their superclass, ''NSMutableData'' while providing a default implementation of the ''NSDiscardableContent'' protocol. All ''NSPurgeableData'' objects begin "accessed" to ensure that they are not instantly discarded. The ''NSDiscardableContent/beginContentAccess()'' method marks the object's bytes as "accessed," thus protecting them from being discarded, and must be called before accessing the object, or else an exception will be raised. This method returns \ if the bytes have not been discarded and if they have been successfully marked as "accessed". Any method that directly or indirectly accesses these bytes or their length when they are not "accessed" will raise an exception. When you are done with the data, call ''NSDiscardableContent/endContentAccess()'' to allow them to be discarded in order to quickly free up memory. You may use these objects by themselves, and do not necessarily have to use them in conjunction with ''NSCache'' to get the purging behavior. The ''NSCache'' class incorporates a caching mechanism with some auto-removal policies to ensure that its memory footprint does not get too large. ''NSPurgeableData'' objects should not be used as keys in hashing-based collections, because the value of the bytes pointer can change after every mutation of the data. + * @details Purgeable Data * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example diff --git a/include/generated/quit_command.h b/include/generated/quit_command.h index ab2d952b..6483c816 100644 --- a/include/generated/quit_command.h +++ b/include/generated/quit_command.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSQuitCommand` (Foundation). - * @details A command that quits the specified app. The quit command may optionally specify how to handle modified documents (automatically save changes, don't save them, or ask the user). For details, see the description for the 'quit' command in "Apple Events Sent By the Mac OS" in [How Cocoa Applications Handle Apple Events](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_handle_AEs/SAppsHandleAEs.html\#//apple_ref/doc/uid/20001239) in [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html\#//apple_ref/doc/uid/TP40002164). 'NSQuitCommand' is part of Cocoa's built-in scripting support. Most applications don't need to subclass 'NSQuitCommand' or call its methods. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptCommand. * @@ -33,7 +32,6 @@ namespace cocoon explicit QuitCommand(Adopt adopt); /** * @brief Returns the `saveOptions` property of `NSQuitCommand`. - * @details The save options specified by the command. * @return The converted Objective-C result. */ SaveOptions save_options() const; diff --git a/include/generated/range_specifier.h b/include/generated/range_specifier.h index e9230d28..e113b85b 100644 --- a/include/generated/range_specifier.h +++ b/include/generated/range_specifier.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSRangeSpecifier` (Foundation). - * @details A specifier for a range of objects in a container. An 'NSRangeSpecifier' object specifies a range (that is, an uninterrupted series) of objects in a container through two delimiting objects. The range is represented by two object specifiers, a start specifier and an end specifier, which can be of any specifier type (such as ''NSIndexSpecifier'' or ''NSWhoseSpecifier'' object). These specifiers are evaluated in the context of the same container object as the range specifier itself. You don't normally subclass 'NSRangeSpecifier'. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptObjectSpecifier. * @@ -49,25 +48,21 @@ namespace cocoon explicit RangeSpecifier(Adopt adopt); /** * @brief Returns the `endSpecifier` property of `NSRangeSpecifier`. - * @details The specifier for the end of the range. * @return The converted Objective-C result. */ ScriptObjectSpecifier end_specifier() const; /** * @brief Sets the `endSpecifier` property of `NSRangeSpecifier`. - * @details The specifier for the end of the range. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_end_specifier(const ScriptObjectSpecifier& value) const; /** * @brief Returns the `startSpecifier` property of `NSRangeSpecifier`. - * @details The specifier for the beginning of the range. * @return The converted Objective-C result. */ ScriptObjectSpecifier start_specifier() const; /** * @brief Sets the `startSpecifier` property of `NSRangeSpecifier`. - * @details The specifier for the beginning of the range. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_start_specifier(const ScriptObjectSpecifier& value) const; diff --git a/include/generated/recursive_lock.h b/include/generated/recursive_lock.h index cb9d3172..ceda817e 100644 --- a/include/generated/recursive_lock.h +++ b/include/generated/recursive_lock.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSRecursiveLock` (Foundation). - * @details A lock that may be acquired multiple times by the same thread without causing a deadlock. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,26 +44,22 @@ namespace cocoon explicit RecursiveLock(Adopt adopt); /** * @brief Calls `-[NSRecursiveLock lockBeforeDate:]`. - * @details Attempts to acquire a lock before a given date and returns a Boolean value indicating whether the attempt was successful. * @param limit Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool lock_before_date(const Date& limit) const; /** * @brief Calls `-[NSRecursiveLock tryLock]`. - * @details Attempts to acquire a lock and immediately returns a Boolean value that indicates whether the attempt was successful. * @return The converted Objective-C result. */ bool try_lock() const; /** * @brief Returns the `name` property of `NSRecursiveLock`. - * @details The name associated with the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSRecursiveLock`. - * @details The name associated with the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; diff --git a/include/generated/refresh_controller.h b/include/generated/refresh_controller.h deleted file mode 100644 index 224ed2bb..00000000 --- a/include/generated/refresh_controller.h +++ /dev/null @@ -1,152 +0,0 @@ -#pragma once - -#include "generated/availability.h" - -#ifdef COCOON_MACOS_27 -#include "generated/enums.h" -#include "generated/structs.h" -#include "object.h" -#include "types.h" - -namespace cocoon -{ - class AttributedString; - class Color; - - /** - * @brief C++ handle for the Objective-C class `NSRefreshController` (AppKit). - * @details A controller that provides pull-to-refresh functionality for scroll views. 'NSRefreshController' enables users to trigger refresh operations by pulling down on scrollable content. Add a refresh controller to an 'NSScrollView' to provide this functionality. Configure the target and action to handle refresh events. - * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. - * - * @par Example - * @code - * #include - * - * cocoon::RefreshController refresh_controller; - * refresh_controller.set_action("text"); - * @endcode - * - * @par Common tasks - * Snippets built from this class's own members (values are placeholders). - * @code - * cocoon::RefreshController refresh_controller{}; - * refresh_controller.set_action("text"); - * auto action = refresh_controller.action(); - * refresh_controller.set_attributed_title(cocoon::AttributedString()); - * auto attributed_title = refresh_controller.attributed_title(); - * refresh_controller.set_tint_color(cocoon::Color()); - * auto tint_color = refresh_controller.tint_color(); - * refresh_controller.begin_refreshing(); - * refresh_controller.end_refreshing(); - * @endcode - * @see https://developer.apple.com/documentation/appkit/nsrefreshcontroller - */ - class RefreshController : public Object - { - public: - /// @brief Creates a new `NSRefreshController` instance and returns a handle to it. - explicit RefreshController(); - /// @brief Creates a null handle that refers to no native object. - RefreshController(std::nullptr_t); - /// @brief Wraps an existing retained native object without creating a new one. - explicit RefreshController(Adopt adopt); -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSRefreshController beginRefreshing]`. - * @details Tells the refresh controller that a refresh operation has begun. Call this method to programmatically start a refresh operation. The refresh controller enters the refreshing state and displays its activity indicator. This is typically used when you want to show a refresh initiated by something other than user interaction. - */ - void begin_refreshing() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSRefreshController endRefreshing]`. - * @details Tells the refresh controller that a refresh operation has ended. Call this method when your refresh operation completes. The refresh controller returns to its default appearance and exits the refreshing state. - */ - void end_refreshing() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `action` property of `NSRefreshController`. - * @details The action method to call when refresh is triggered. - * @return The converted Objective-C result. - */ - std::string action() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `action` property of `NSRefreshController`. - * @details The action method to call when refresh is triggered. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_action(const std::string& value) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `attributedTitle` property of `NSRefreshController`. - * @details The styled text to display in the refresh controller. Use this property to provide additional context about the refresh operation. - * @return The converted Objective-C result. - */ - AttributedString attributed_title() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `attributedTitle` property of `NSRefreshController`. - * @details The styled text to display in the refresh controller. Use this property to provide additional context about the refresh operation. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_attributed_title(const AttributedString& value) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `isRefreshing` property of `NSRefreshController`. - * @details A Boolean value indicating whether a refresh operation is in progress. The default value of this property is 'NO'. When the user triggers a refresh, this property automatically becomes 'YES'. Call ''endRefreshing'' when your refresh operation completes to reset this property to 'NO'. - * @return The converted Objective-C result. - */ - bool is_refreshing() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `target` property of `NSRefreshController`. - * @details The target object that receives action messages. - * @return The converted Objective-C result. - */ - Object target() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `target` property of `NSRefreshController`. - * @details The target object that receives action messages. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_target(const Object& value) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `tintColor` property of `NSRefreshController`. - * @details The tint color for the refresh controller. This color is used for the refresh indicator. - * @return The converted Objective-C result. - */ - Color tint_color() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `tintColor` property of `NSRefreshController`. - * @details The tint color for the refresh controller. This color is used for the refresh indicator. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_tint_color(const Color& value) const; -#endif - }; -} - -#endif diff --git a/include/generated/regular_expression.h b/include/generated/regular_expression.h index d0fcc031..85ba11f7 100644 --- a/include/generated/regular_expression.h +++ b/include/generated/regular_expression.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSRegularExpression` (Foundation). - * @details An immutable representation of a compiled regular expression that you apply to Unicode strings. The fundamental matching method for ''NSRegularExpression'' is a Block iterator method that allows clients to supply a Block object which will be invoked each time the regular expression matches a portion of the target string. There are additional convenience methods for returning all the matches as an array, the total number of matches, the first match, and the range of the first match. An individual match is represented by an instance of the ''NSTextCheckingResult'' class, which carries information about the overall matched range (via its ''NSTextCheckingResult/range'' property), and the range of each individual capture group (via the ''NSTextCheckingResult/range(at:)'' method). For basic ''NSRegularExpression'' objects, these match results will be of type ''NSTextCheckingResult/CheckingType/regularExpression'', but subclasses may use other types. > Note: > ''NSRegularExpression'' conforms to the International Components for Unicode ([ICU](https://unicode-org.github.io/icu/)) specification for [regular expressions](https://unicode-org.github.io/icu/userguide/strings/regexp.html). \#\#\# Examples Using NSRegularExpression What follows are a set of graduated examples for using the 'NSRegularExpression' class. All these examples use the regular expression '\\\\b(a|b)(c|d)\\\\b' as their regular expression. This snippet creates a regular expression to match two-letter words, in which the first letter is "a" or "b" and the second letter is "c" or "d". Specifying ''Options/caseInsensitive'' means that matches will be case-insensitive, so this will match "BC", "aD", and so forth, as well as their lower-case equivalents. \@TabNavigator { \@Tab("Swift") { '''swift do { let regex = try NSRegularExpression(pattern: "\\\\b(a|b)(c|d)\\\\b", options: .caseInsensitive) } catch let error as NSError { print("Error creating NSRegularExpression: \\(error)") } ''' } \@Tab("Objective-C") { '''objc NSError error = NULL; NSRegularExpression regex = [NSRegularExpression regularExpressionWithPattern:\@"\\\\b(a|b)(c|d)\\\\b" options:NSRegularExpressionCaseInsensitive error:&error]; ''' } } The ''numberOfMatches(in:options:range:)'' method provides a simple mechanism for counting the number of matches in a given range of a string. \@TabNavigator { \@Tab("Swift") { '''swift let numberOfMatches = regex.numberOfMatches(in: string, options: [], range: NSRange(location: 0, length: string.utf16.count)) ''' } \@Tab("Objective-C") { '''objc NSUInteger numberOfMatches = [regex numberOfMatchesInString:string options:0 range:NSMakeRange(0, [string length])]; ''' } } If you are interested only in the overall range of the first match, the ''rangeOfFirstMatch(in:options:range:)'' method provides it for you. Some regular expressions (though not the example pattern) can successfully match a zero-length range, so the comparison of the resulting range with '{NSNotFound, 0}' is the most reliable way to determine whether there was a match or not. The example regular expression contains two capture groups, corresponding to the two sets of parentheses, one for the first letter, and one for the second. If you are interested in more than just the overall matched range, you want to obtain an ''NSTextCheckingResult'' object corresponding to a given match. This object provides information about the overall matched range, via its ''NSTextCheckingResult/range'' property, and also supplies the capture group ranges, via the ''NSTextCheckingResult/range(at:)'' method. The first capture group range is given by '[result rangeAtIndex:1]', the second by '[result rangeAtIndex:2]'. Sending a result the ''NSTextCheckingResult/range(at:)'' message and passing '0' is equivalent to '[result range]'. If the result returned is non-'nil', then '[result range]' will always be a valid range, so it is not necessary to compare it against '{NSNotFound, 0}'. However, for some regular expressions (though not the example pattern) some capture groups may or may not participate in a given match. If a given capture group does not participate in a given match, then '[result rangeAtIndex:idx]' will return '{NSNotFound, 0}'. \@TabNavigator { \@Tab("Swift") { '''swift let rangeOfFirstMatch = regex.rangeOfFirstMatch(in: string, options: [], range: NSRange(location: 0, length: string.utf16.count)) if rangeOfFirstMatch.location != NSNotFound { let substringForFirstMatch = (string as NSString).substring(with: rangeOfFirstMatch) } ''' } \@Tab("Objective-C") { '''objc NSRange rangeOfFirstMatch = [regex rangeOfFirstMatchInString:string options:0 range:NSMakeRange(0, [string length])]; if (!NSEqualRanges(rangeOfFirstMatch, NSMakeRange(NSNotFound, 0))) { NSString substringForFirstMatch = [string substringWithRange:rangeOfFirstMatch]; } ''' } } The ''matches(in:options:range:)'' returns all the matching results. \@TabNavigator { \@Tab("Swift") { '''swift let matches = regex.matches(in: string, options: [], range: NSRange(location: 0, length: string.utf16.count)) for match in matches { let matchRange = match.range let firstHalfRange = match.range(at: 1) let secondHalfRange = match.range(at: 2) } ''' } \@Tab("Objective-C") { '''objc NSArray matches = [regex matchesInString:string options:0 range:NSMakeRange(0, [string length])]; for (NSTextCheckingResult match in matches) { NSRange matchRange = [match range]; NSRange firstHalfRange = [match rangeAtIndex:1]; NSRange secondHalfRange = [match rangeAtIndex:2]; } ''' } } The ''firstMatch(in:options:range:)'' method is similar to ''matches(in:options:range:)'' but it returns only the first match. \@TabNavigator { \@Tab("Swift") { '''swift if let match = regex.firstMatch(in: string, options: [], range: NSRange(location: 0, length: string.utf16.count)) { let matchRange = match.range let firstHalfRange = match.range(at: 1) let secondHalfRange = match.range(at: 2) } ''' } \@Tab("Objective-C") { '''objc NSTextCheckingResult match = [regex firstMatchInString:string options:0 range:NSMakeRange(0, [string length])]; if (match) { NSRange matchRange = [match range]; NSRange firstHalfRange = [match rangeAtIndex:1]; NSRange secondHalfRange = [match rangeAtIndex:2]; } ''' } } The Block enumeration method ''enumerateMatches(in:options:range:using:)'' is the most general and flexible of the matching methods of 'NSRegularExpression'. It allows you to iterate through matches in a string, performing arbitrary actions on each as specified by the code in the Block and to stop partway through if desired. In the following example case, the iteration is stopped after a certain number of matches have been found. If neither of the special options ''MatchingOptions/reportProgress'' or ''MatchingOptions/reportCompletion'' is specified, then the result argument to the Block is guaranteed to be non-'nil', and as mentioned before, it is guaranteed to have a valid overall range. See ''MatchingOptions'' for the significance of ''MatchingOptions/reportProgress'' or ''MatchingOptions/reportCompletion''. \@TabNavigator { \@Tab("Swift") { '''swift var count = 0 regex.enumerateMatches(in: string, options: [], range: NSRange(location: 0, length: string.utf16.count)) { match, flags, stop in guard let match = match else { return } let matchRange = match.range let firstHalfRange = match.range(at: 1) let secondHalfRange = match.range(at: 2) count += 1 if count >= 100 { stop = true } } ''' } \@Tab("Objective-C") { '''objc block NSUInteger count = 0; [regex enumerateMatchesInString:string options:0 range:NSMakeRange(0, [string length]) usingBlock:^(NSTextCheckingResult match, NSMatchingFlags flags, BOOL stop){ NSRange matchRange = [match range]; NSRange firstHalfRange = [match rangeAtIndex:1]; NSRange secondHalfRange = [match rangeAtIndex:2]; if (++count >= 100) stop = YES; }]; ''' } } 'NSRegularExpression' also provides simple methods for performing find-and-replace operations on a string. The following example returns a modified copy, but there is a corresponding method for modifying a mutable string in place. The template specifies what is to be used to replace each match, with '$0' representing the contents of the overall matched range, '$1' representing the contents of the first capture group, and so on. In this case, the template reverses the two letters of the word. \@TabNavigator { \@Tab("Swift") { '''swift let modifiedString = regex.stringByReplacingMatches(in: string, options: [], range: NSRange(location: 0, length: string.utf16.count), withTemplate: "$2$1") ''' } \@Tab("Objective-C") { '''objc NSString modifiedString = [regex stringByReplacingMatchesInString:string options:0 range:NSMakeRange(0, [string length]) withTemplate:\@"$2$1"]; ''' } } \#\#\# Concurrency and Thread Safety 'NSRegularExpression' is designed to be immutable and thread safe, so that a single instance can be used in matching operations on multiple threads at once. However, the string on which it is operating should not be mutated during the course of a matching operation, whether from another thread or from within the Block used in the iteration. \#\#\# Regular Expression Syntax The following tables describe the character expressions used by the regular expression to match patterns within a string, the pattern operators that specify how many times a pattern is matched and additional matching restrictions, and the last table specifies flags that can be included in the regular expression pattern that specify search behavior over multiple lines (these flags can also be specified using the ''Options'' option flags. \#\#\#\# Regular Expression Metacharacters Table 1: Character sequences used to match characters within a string. | Character Expression | Description | |---|---| | '\\a' | Match a BELL, '\\u0007' | | '\\A' | Match at the beginning of the input. Differs from '^' in that '\\A' will not match after a new line within the input. | | '\\b, outside of a [Set]' | Match if the current position is a word boundary. Boundaries occur at the transitions between word ('\\w') and non-word ('\\W') characters, with combining marks ignored. For better word boundaries, see ''Options/useUnicodeWordBoundaries''. | | '\\b, within a [Set]' | Match a BACKSPACE, '\\u0008'. | | '\\B' | Match if the current position is not a word boundary. | | '\\cX' | Match a 'control-X' character | | '\\d' | Match any character with the Unicode General Category of Nd (Number, Decimal Digit.) | | '\\D' | Match any character that is not a decimal digit. | | '\\e' | Match an 'ESCAPE', '\\u001B'. | | '\\E' | Terminates a '\\Q ... \\E' quoted sequence. | | '\\f' | Match a FORM FEED, '\\u000C'. | | '\\G' | Match if the current position is at the end of the previous match. | | '\\n' | Match a 'LINE FEED', '\\u000A'. | | '\\N{'UNICODE CHARACTER NAME'}' | Match the named character. | | '\\p{'UNICODE PROPERTY NAME'}' | Match any character with the specified Unicode Property. | | '\\P{'UNICODE PROPERTY NAME'}' | Match any character not having the specified Unicode Property. | | '\\Q' | Quotes all following characters until '\\E'. | | '\\r' | Match a CARRIAGE RETURN, \\u000D. | | '\\s' | Match a white space character. White space is defined as [\\t\\n\\f\\r\\p{Z}]. | | '\\S' | Match a non-white space character. | | '\\t' | Match a HORIZONTAL TABULATION, '\\u0009'. | | '\\u'hhhh | Match the character with the hex value hhhh. | | '\\U'hhhhhhhh | Match the character with the hex value hhhhhhhh. Exactly eight hex digits must be provided, even though the largest Unicode code point is '\\U0010ffff'. | | '\\w' | Match a word character. Word characters are [\\p{Ll}\\p{Lu}\\p{Lt}\\p{Lo}\\p{Nd}]. | | '\\W' | Match a non-word character. | | '\\x{'hhhh'}' | Match the character with hex value hhhh. From one to six hex digits may be supplied. | | '\\x'hh | Match the character with two digit hex value hh. | | '\\X' | Match a Grapheme Cluster. | | '\\Z' | Match if the current position is at the end of input, but before the final line terminator, if one exists. | | '\\z' | Match if the current position is at the end of input. | | '\\'n | Back Reference. Match whatever the n_th capturing group matched. n must be a number '≥ 1' and '≤' total number of capture groups in the pattern. | | '\\0'ooo | Match an Octal character. ooo is from one to three octal digits. '0377' is the largest allowed Octal character. The leading zero is required; it distinguishes Octal constants from back references. | | '['pattern']' | Match any one character from the pattern. | | '.' | Match any character. See ''Options/dotMatchesLineSeparators'' and the 's' character expression in Table 4. | | '^' | Match at the beginning of a line. See ''Options/anchorsMatchLines'' and the '\\m' character expression in Table 4. | | '$' | Match at the end of a line. See ''Options/anchorsMatchLines'' and the 'm' character expression in Table 4. | | '\\' | Quotes the following character. Characters that must be quoted to be treated as literals are ' ? + [ ( ) { } ^ $ | \\ . /' | \#\#\#\# Regular Expression Operators Table 2: Regular expression operators. | Operator | Description | |---|---| | '|' | Alternation. A'|'B matches either A or B. | | '' | Match '0' or more times. Match as many times as possible. | | '+' | Match '1' or more times. Match as many times as possible. | | '?' | Match zero or one times. Prefer one. | | '{'n'}' | Match exactly n times. | | '{'n',}' | Match at least n times. Match as many times as possible. | | '{'n','m'}' | Match between n and m times. Match as many times as possible, but not more than m. | | '?' | Match '0' or more times. Match as few times as possible. | | '+?' | Match 1 or more times. Match as few times as possible. | | '??' | Match zero or one times. Prefer zero. | | '{'n'}?' | Match exactly n times. | | '{'n',}?' | Match at least n times, but no more than required for an overall pattern match. | | '{'n','m'}?' | Match between n and m times. Match as few times as possible, but not less than n. | | '+' | Match 0 or more times. Match as many times as possible when first encountered. Do not retry with fewer, even if overall match fails (possessive match). | | '++' | Match 1 or more times (possessive match). | | '?+' | Match zero or one times (possessive match). | | '{'n'}+' | Match exactly n times. | | '{'n',}+' | Match at least n times (possessive match). | | '{'n','m'}+' | Match between n and m times (possessive match). | | '('...')' | Capturing parentheses. Range of input that matched the parenthesized subexpression is available after the match. | | '(?:'...')' | Non-capturing parentheses. Groups the included pattern, but does not provide capturing of matching text. Somewhat more efficient than capturing parentheses. | | '(?>'...')' | Atomic-match parentheses. First match of the parenthesized subexpression is the only one tried; if it does not lead to an overall pattern match, back up the search for a match to a position before the "'(?>'" | | '(?\# ... )' | Free-format comment '(?\# comment )'. | | '(?= ... )' | Look-ahead assertion. True if the parenthesized pattern matches at the current input position, but does not advance the input position. | | '(?! ... )' | Negative look-ahead assertion. True if the parenthesized pattern does not match at the current input position. Does not advance the input position. | | '(?\<= ... )' | Look-behind assertion. True if the parenthesized pattern matches text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no \\ or + operators.) | | '(?\. | | '(?ismwx-ismwx)' | Flag settings. Change the flag settings. Changes apply to the portion of the pattern following the setting. For example, (?i) changes to a case insensitive match.The flags are defined in \. | \#\#\#\# Template Matching Format The 'NSRegularExpression' class provides find-and-replace methods for both immutable and mutable strings using the technique of template matching. Table 3: Find-and-replace syntax. | Character | Descriptions | |---|---| | '$'n | The text of capture group n will be substituted for $n. n must be '>= 0' and not greater than the number of capture groups. A '$' not followed by a digit has no special meaning, and will appear in the substitution text as itself, a '$'. | | '\\' | Treat the following character as a literal, suppressing any special meaning. Backslash escaping in substitution text is only required for '$' and '\\', but may be used on any other character without bad effects. | The replacement string is treated as a template, with '$0' being replaced by the contents of the matched range, '$1' by the contents of the first capture group, and so on. Additional digits beyond the maximum required to represent the number of capture groups will be treated as ordinary characters, as will a '$' not followed by digits. Backslash will escape both '$' and '\\'. \#\#\#\# Flag Options The following flags control various aspects of regular expression matching. These flag values may be specified within the pattern using the '(?ismx-ismx)' pattern options. Equivalent behaviors can be specified for the entire pattern when an 'NSRegularExpression' is initialized, using the ''Options'' option flags. Table 4: Regular expression matching flags. | Flag (Pattern) | Description | |---|---| | i | If set, matching will take place in a case-insensitive manner. | | x | If set, allow use of white space and \#comments within patterns | | s | If set, a "'.'" in a pattern will match a line terminator in the input text. By default, it will not. Note that a 'carriage-return / line-feed pair' in text behave as a single line terminator, and will match a single "'.'" in a regular expression pattern | | m | Control the behavior of "'^'" and "'$'" in a pattern. By default these will only match at the start and end, respectively, of the input text. If this flag is set, "'^'" and "'$'" will also match at the start and end of each line within the input text. | | w | Controls the behavior of '\\b' in a pattern. If set, word boundaries are found according to the definitions of word found in Unicode UAX 29, Text Boundaries. By default, word boundaries are identified by means of a simple classification of characters as either "word" or "non-word", which approximates traditional regular expression behavior. The results obtained with the two options can be quite different in runs of spaces and other non-word characters. | \#\#\# Performance 'NSRegularExpression' implements a nondeterministic finite automaton matching engine. As such, complex regular expression patterns containing multiple '' or '+' operators may result in poor performance when attempting to perform matches — particularly failing to match a given input. For more information, see the [“Performance Tips” section of the ICU User Guide](http://userguide.icu-project.org/strings/regexp\#TOC-Performance-Tips). \#\#\# ICU License Tables 1, 2, 3, and 4 are reproduced from the ICU User Guide, Copyright (c) 2000 - 2009 IBM and Others, which are licensed under the following terms: COPYRIGHT AND PERMISSION NOTICE Copyright (c) 1995-2009 International Business Machines Corporation and others. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. All trademarks and registered trademarks mentioned herein are the property of their respective owners. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -43,7 +42,7 @@ namespace cocoon explicit RegularExpression(Adopt adopt); /** * @brief Calls `-[NSRegularExpression enumerateMatchesInString:options:range:usingBlock:]`. - * @details Enumerates the string allowing the Block to handle each regular expression match. - Parameter string: The string. - Parameter options: The matching options to report. See 'NSMatchingOptions' for the supported values. - Parameter range: The range of the string to test. - Parameter block: The Block enumerates the matches of the regular expression in the string. The block takes three arguments: 'result' (an 'NSTextCheckingResult' specifying the match), 'flags' (the current state of matching progress), and 'stop' (a reference to a Boolean value that the Block can set to 'YES' to stop further processing). This method is the fundamental matching method for regular expressions and is suitable for overriding by subclassers. There are additional convenience methods for returning all the matches as an array, the total number of matches, the first match, and the range of the first match. + * @details The fundamental matching method on NSRegularExpression is a block iterator. There are several additional convenience methods, for returning all matches at once, the number of matches, the first match, or the range of the first match. Each match is specified by an instance of NSTextCheckingResult (of type NSTextCheckingTypeRegularExpression) in which the overall match range is given by the range property (equivalent to rangeAtIndex:0) and any capture group ranges are given by rangeAtIndex: for indexes from 1 to numberOfCaptureGroups. {NSNotFound, 0} is used if a particular capture group does not participate in the match. * @param string Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -52,21 +51,20 @@ namespace cocoon void enumerate_matches_in_string(const std::string& string, MatchingOptions options, const Range& range, std::function block) const; /** * @brief Calls `+[NSRegularExpression escapedPatternForString:]`. - * @details Returns a string by adding backslash escapes as necessary to protect any characters that would match as pattern metacharacters. - Parameter string: The string. - Returns: The escaped string. Returns a string by adding backslash escapes as necessary to the given string, to escape any characters that would otherwise be treated as pattern metacharacters. You typically use this method to match on a particular string within a larger pattern. + * @details This class method will produce a string by adding backslash escapes as necessary to the given string, to escape any characters that would otherwise be treated as pattern metacharacters. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string escaped_pattern_for_string(const std::string& string); /** * @brief Calls `+[NSRegularExpression escapedTemplateForString:]`. - * @details Returns a template string by adding backslash escapes as necessary to protect any characters that would match as pattern metacharacters. - Parameter string: The template string. - Returns: The escaped template string. Returns a string by adding backslash escapes as necessary to the given string, to escape any characters that would otherwise be treated as template metacharacters. + * @details This class method will produce a string by adding backslash escapes as necessary to the given string, to escape any characters that would otherwise be treated as template metacharacters. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string escaped_template_for_string(const std::string& string); /** * @brief Calls `-[NSRegularExpression firstMatchInString:options:range:]`. - * @details Returns the first match of the regular expression within the specified range of the string. - Parameter string: The string to search. - Parameter options: The matching options to use. See 'NSMatchingOptions' for possible values. - Parameter range: The range of the string to search. - Returns: An 'NSTextCheckingResult' object. This result gives the overall matched range via its 'range' property, and the range of each individual capture group via its 'rangeAtIndex:' method. The range {'NSNotFound', 0} is returned if one of the capture groups did not participate in this particular match. * @param string Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -75,7 +73,6 @@ namespace cocoon TextCheckingResult first_match_in_string(const std::string& string, MatchingOptions options, const Range& range) const; /** * @brief Calls `-[NSRegularExpression matchesInString:options:range:]`. - * @details Returns an array containing all the matches of the regular expression in the string. - Parameter string: The string to search. - Parameter options: The matching options to use. See 'NSMatchingOptions' for possible values. - Parameter range: The range of the string to search. - Returns: An array of 'NSTextCheckingResult' objects. Each result gives the overall matched range via its 'range' property, and the range of each individual capture group via its 'rangeAtIndex:' method. The range {'NSNotFound', 0} is returned if one of the capture groups did not participate in this particular match. * @param string Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -84,7 +81,6 @@ namespace cocoon std::vector matches_in_string(const std::string& string, MatchingOptions options, const Range& range) const; /** * @brief Calls `-[NSRegularExpression numberOfMatchesInString:options:range:]`. - * @details Returns the number of matches of the regular expression within the specified range of the string. - Parameter string: The string to search. - Parameter options: The matching options to use. See 'NSMatchingOptions' for possible values. - Parameter range: The range of the string to search. - Returns: The number of matches of the regular expression. * @param string Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -93,7 +89,6 @@ namespace cocoon std::uint64_t number_of_matches_in_string(const std::string& string, MatchingOptions options, const Range& range) const; /** * @brief Calls `-[NSRegularExpression rangeOfFirstMatchInString:options:range:]`. - * @details Returns the range of the first match of the regular expression within the specified range of the string. - Parameter string: The string to search. - Parameter options: The matching options to use. See 'NSMatchingOptions' for possible values. - Parameter range: The range of the string to search. - Returns: The range of the first match. Returns '{NSNotFound, 0}' if no match is found. * @param string Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -102,7 +97,6 @@ namespace cocoon Range range_of_first_match_in_string(const std::string& string, MatchingOptions options, const Range& range) const; /** * @brief Calls `-[NSRegularExpression replaceMatchesInString:options:range:withTemplate:]`. - * @details Replaces regular expression matches within the mutable string using the template string. - Parameter string: The mutable string to search and replace values within. - Parameter options: The matching options to use. See 'NSMatchingOptions' for possible values. - Parameter range: The range of the string to search. - Parameter templ: The substitution template used when replacing matching instances. - Returns: The number of matches. * @param string Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -112,7 +106,7 @@ namespace cocoon std::uint64_t replace_matches_in_string(const std::string& string, MatchingOptions options, const Range& range, const std::string& templ) const; /** * @brief Calls `-[NSRegularExpression replacementStringForResult:inString:offset:template:]`. - * @details Used to perform template substitution for a single result for clients implementing their own replace functionality. - Parameter result: The result of the single match. - Parameter string: The string from which the result was matched. - Parameter offset: The offset to be added to the location of the result in the string. - Parameter templ: The replacement template. - Returns: A replacement string. For clients implementing their own replace functionality, this is a method to perform the template substitution for a single result, given the string from which the result was matched, an offset to be added to the location of the result in the string (for example, in cases that modifications to the string moved the result since it was matched), and a replacement template. + * @details For clients implementing their own replace functionality, this is a method to perform the template substitution for a single result, given the string from which the result was matched, an offset to be added to the location of the result in the string (for example, in case modifications to the string moved the result since it was matched), and a replacement template. * @param result Argument converted to the Objective-C parameter of the same role. * @param string Argument converted to the Objective-C parameter of the same role. * @param offset Argument converted to the Objective-C parameter of the same role. @@ -122,7 +116,7 @@ namespace cocoon std::string replacement_string_for_result(const TextCheckingResult& result, const std::string& string, std::int64_t offset, const std::string& templ) const; /** * @brief Calls `-[NSRegularExpression stringByReplacingMatchesInString:options:range:withTemplate:]`. - * @details Returns a new string containing matching regular expressions replaced with the template string. - Parameter string: The string to search for values within. - Parameter options: The matching options to use. See 'NSMatchingOptions' for possible values. - Parameter range: The range of the string to search. - Parameter templ: The substitution template used when replacing matching instances. - Returns: A string with matching regular expressions replaced by the template string. The replacement is treated as a template, with '$0' being replaced by the contents of the matched range, '$1' by the contents of the first capture group, and so on. Additional digits beyond the maximum required to represent the number of capture groups will be treated as ordinary characters, as will a '$' not followed by digits. Backslash will escape both '$' and itself. + * @details NSRegularExpression also provides find-and-replace methods for both immutable and mutable strings. The replacement is treated as a template, with $0 being replaced by the contents of the matched range, $1 by the contents of the first capture group, and so on. Additional digits beyond the maximum required to represent the number of capture groups will be treated as ordinary characters, as will a $ not followed by digits. Backslash will escape both $ and itself. * @param string Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param range Argument converted to the Objective-C parameter of the same role. @@ -132,19 +126,16 @@ namespace cocoon std::string string_by_replacing_matches_in_string(const std::string& string, MatchingOptions options, const Range& range, const std::string& templ) const; /** * @brief Returns the `numberOfCaptureGroups` property of `NSRegularExpression`. - * @details Returns the number of capture groups in the regular expression. A capture group consists of each possible match within a regular expression. Each capture group can then be used in a replacement template to insert that value into a replacement string. This value puts a limit on the values of 'n' for '$n' in templates, and it determines the number of ranges in the returned 'NSTextCheckingResult' instances returned in the match methods. * @return The converted Objective-C result. */ std::uint64_t number_of_capture_groups() const; /** * @brief Returns the `options` property of `NSRegularExpression`. - * @details Returns the options used when the regular expression option was created. The options property specifies aspects of the regular expression matching that are always used when matching the regular expression. For example, if the expression is case sensitive, allows comments, ignores metacharacters, etc. * @return The converted Objective-C result. */ RegularExpressionOptions options() const; /** * @brief Returns the `pattern` property of `NSRegularExpression`. - * @details Returns the regular expression pattern. * @return The converted Objective-C result. */ std::string pattern() const; diff --git a/include/generated/relative_date_time_formatter.h b/include/generated/relative_date_time_formatter.h index 9b9f1d75..2d699c3e 100644 --- a/include/generated/relative_date_time_formatter.h +++ b/include/generated/relative_date_time_formatter.h @@ -15,7 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSRelativeDateTimeFormatter` (Foundation). - * @details A formatter that creates locale-aware string representations of a relative date or time. Use the strings that the formatter produces, such as "1 hour ago", "in 2 weeks", "yesterday", and "tomorrow" as standalone strings. Embedding them in other strings may not be grammatically correct. + * @details NSRelativeDateTimeFormatter provides locale-aware formatting of a relative date or time, such as "1 hour ago", "in 2 weeks", "yesterday", and "tomorrow." Note that the string produced by the formatter should only be used in a standalone manner as it may not be grammatically correct to embed the string in longer strings. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Formatter. * @@ -63,82 +63,82 @@ namespace cocoon std::string localized_string_for_date(const Date& date, const Date& reference_date) const; /** * @brief Calls `-[NSRelativeDateTimeFormatter localizedStringFromDateComponents:]`. - * @details Returns a formatted string representing a relative time from the given date components. Negative component values are evaluated as a date in the past. This method formats the value of the least granular unit in the 'NSDateComponents' object, and does not provide a compound format of the date component. Note this method only supports the following components: year, month, week of month, day, hour, minute, and second. The rest will be ignored. + * @details Convenience method for formatting a relative time represented by an NSDateComponents object. Negative component values are evaluated as a date in the past. This method formats the value of the least granular unit in the NSDateComponents object, and does not provide a compound format of the date component. Note this method only supports the following components: year, month, week of month, day, hour, minute, and second. The rest will be ignored. * @param date_components Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_from_date_components(const DateComponents& date_components) const; /** * @brief Calls `-[NSRelativeDateTimeFormatter localizedStringFromTimeInterval:]`. - * @details Returns a formatted string representing a relative time from the given time interval. Negative time interval is evaluated as a date in the past. + * @details Convenience method for formatting a time interval using the formatter's calendar. Negative time interval is evaluated as a date in the past. * @param time_interval Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string localized_string_from_time_interval(double time_interval) const; /** * @brief Calls `-[NSRelativeDateTimeFormatter stringForObjectValue:]`. - * @details Creates a formatted string for a date relative to the current date and time. To determine the relative interval, the formatter uses '[NSDate date]' as the reference date. - Parameters: - obj: A date object to format. - Returns: A string that represents the date interval between a date and the current date and time, or 'nil' if 'obj' isn't an instance of 'NSDate'. + * @details Inherited from NSFormatter. 'obj' must be an instance of NSDate. Returns nil otherwise. When formatting a relative date using this method, the class uses -[NSDate date] as the reference date. * @param obj Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_for_object_value(const Object& obj) const; /** * @brief Returns the `calendar` property of `NSRelativeDateTimeFormatter`. - * @details Specifies the calendar to use for formatting values that do not have an inherent calendar of their own. Defaults to 'autoupdatingCurrentCalendar'. Also resets to 'autoupdatingCurrentCalendar' on assignment of 'nil'. + * @details Specifies the calendar to use for formatting values that do not have an inherent calendar of their own. Defaults to autoupdatingCurrentCalendar. Also resets to autoupdatingCurrentCalendar on assignment of nil. * @return The converted Objective-C result. */ Calendar calendar() const; /** * @brief Sets the `calendar` property of `NSRelativeDateTimeFormatter`. - * @details Specifies the calendar to use for formatting values that do not have an inherent calendar of their own. Defaults to 'autoupdatingCurrentCalendar'. Also resets to 'autoupdatingCurrentCalendar' on assignment of 'nil'. + * @details Specifies the calendar to use for formatting values that do not have an inherent calendar of their own. Defaults to autoupdatingCurrentCalendar. Also resets to autoupdatingCurrentCalendar on assignment of nil. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_calendar(const Calendar& value) const; /** * @brief Returns the `dateTimeStyle` property of `NSRelativeDateTimeFormatter`. - * @details Specifies how to describe a relative date. For example, "yesterday" vs "1 day ago" in English. Default is 'NSRelativeDateTimeFormatterStyleNumeric'. + * @details Specifies how to describe a relative date. For example, "yesterday" vs "1 day ago" in English. Default is NSRelativeDateTimeFormatterStyleNumeric. * @return The converted Objective-C result. */ RelativeDateTimeFormatterStyle date_time_style() const; /** * @brief Sets the `dateTimeStyle` property of `NSRelativeDateTimeFormatter`. - * @details Specifies how to describe a relative date. For example, "yesterday" vs "1 day ago" in English. Default is 'NSRelativeDateTimeFormatterStyleNumeric'. + * @details Specifies how to describe a relative date. For example, "yesterday" vs "1 day ago" in English. Default is NSRelativeDateTimeFormatterStyleNumeric. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_date_time_style(RelativeDateTimeFormatterStyle value) const; /** * @brief Returns the `formattingContext` property of `NSRelativeDateTimeFormatter`. - * @details Specifies the formatting context of the output. Default is 'NSFormattingContextUnknown'. + * @details Specifies the formatting context of the output. Default is NSFormattingContextUnknown. * @return The converted Objective-C result. */ FormattingContext formatting_context() const; /** * @brief Sets the `formattingContext` property of `NSRelativeDateTimeFormatter`. - * @details Specifies the formatting context of the output. Default is 'NSFormattingContextUnknown'. + * @details Specifies the formatting context of the output. Default is NSFormattingContextUnknown. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_formatting_context(FormattingContext value) const; /** * @brief Returns the `locale` property of `NSRelativeDateTimeFormatter`. - * @details Specifies the locale of the output string. Defaults to and resets on assignment of 'nil' to the calendar's locale. + * @details Specifies the locale of the output string. Defaults to and resets on assignment of nil to the calendar's locale. * @return The converted Objective-C result. */ Locale locale() const; /** * @brief Sets the `locale` property of `NSRelativeDateTimeFormatter`. - * @details Specifies the locale of the output string. Defaults to and resets on assignment of 'nil' to the calendar's locale. + * @details Specifies the locale of the output string. Defaults to and resets on assignment of nil to the calendar's locale. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Locale& value) const; /** * @brief Returns the `unitsStyle` property of `NSRelativeDateTimeFormatter`. - * @details Specifies how to format the quantity or the name of the unit. For example, "1 day ago" vs "one day ago" in English. Default is 'NSRelativeDateTimeFormatterUnitsStyleFull'. + * @details Specifies how to format the quantity or the name of the unit. For example, "1 day ago" vs "one day ago" in English. Default is NSRelativeDateTimeFormatterUnitsStyleFull. * @return The converted Objective-C result. */ RelativeDateTimeFormatterUnitsStyle units_style() const; /** * @brief Sets the `unitsStyle` property of `NSRelativeDateTimeFormatter`. - * @details Specifies how to format the quantity or the name of the unit. For example, "1 day ago" vs "one day ago" in English. Default is 'NSRelativeDateTimeFormatterUnitsStyleFull'. + * @details Specifies how to format the quantity or the name of the unit. For example, "1 day ago" vs "one day ago" in English. Default is NSRelativeDateTimeFormatterUnitsStyleFull. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_units_style(RelativeDateTimeFormatterUnitsStyle value) const; diff --git a/include/generated/relative_specifier.h b/include/generated/relative_specifier.h index e1d6fce6..1bf75633 100644 --- a/include/generated/relative_specifier.h +++ b/include/generated/relative_specifier.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSRelativeSpecifier` (Foundation). - * @details A specifier that indicates an object in a collection by its position relative to another object. You don't normally subclass 'NSRelativeSpecifier'. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptObjectSpecifier. * @@ -49,25 +48,21 @@ namespace cocoon explicit RelativeSpecifier(Adopt adopt); /** * @brief Returns the `baseSpecifier` property of `NSRelativeSpecifier`. - * @details The specifier for the base object relative to which the target is located. * @return The converted Objective-C result. */ ScriptObjectSpecifier base_specifier() const; /** * @brief Sets the `baseSpecifier` property of `NSRelativeSpecifier`. - * @details The specifier for the base object relative to which the target is located. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_base_specifier(const ScriptObjectSpecifier& value) const; /** * @brief Returns the `relativePosition` property of `NSRelativeSpecifier`. - * @details The relative position (before or after) of the object to be located. * @return The converted Objective-C result. */ RelativePosition relative_position() const; /** * @brief Sets the `relativePosition` property of `NSRelativeSpecifier`. - * @details The relative position (before or after) of the object to be located. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_relative_position(RelativePosition value) const; diff --git a/include/generated/responder.h b/include/generated/responder.h index cbe80877..8133a044 100644 --- a/include/generated/responder.h +++ b/include/generated/responder.h @@ -329,7 +329,7 @@ namespace cocoon void tablet_proximity(const Event& event) const; /** * @brief Calls `-[NSResponder touchesBeganWithEvent:]`. - * @details A new set of touches has been recognized. To get the set of touches that began for this view (or descendants of this view): [event touchesMatchingPhase:NSTouchPhaseBegan inView:self]; Note: this is not always the point of contact with the touch device. A touch that transitions from resting to active may be part of a Began set. Note: These 'touches' responder methods are used for indirect touches and touchbar devices only. They are not used for Sidecar devices. + * @details A new set of touches has been recognized. To get the set of touches that began for this view (or descendants of this view): [event touchesMatchingPhase:NSTouchPhaseBegan inView:self]; Note: this is not always the point of contact with the touch device. A touch that transitions from resting to active may be part of a Began set. * @param event Argument converted to the Objective-C parameter of the same role. */ void touches_began_with_event(const Event& event) const; diff --git a/include/generated/run_loop.h b/include/generated/run_loop.h index a87f7ece..825aeeed 100644 --- a/include/generated/run_loop.h +++ b/include/generated/run_loop.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSRunLoop` (Foundation). - * @details The programmatic interface to objects that manage input sources. A ''RunLoop'' object processes input for sources, such as mouse and keyboard events from the window system and ''Port'' objects. A ''RunLoop'' object also processes ''Timer'' events. Your application neither creates nor explicitly manages ''RunLoop'' objects. The system creates a ''RunLoop'' object as needed for each ''Thread'' object, including the application's main thread. If you need to access the current thread's run loop, use the class method ''current''. Note that from the perspective of ''RunLoop'', ''Timer'' objects aren't "input"—they're a special type, and they don't cause the run loop to return when they fire. > Warning: > The ''RunLoop'' class is generally not thread-safe, and you must call its methods only within the context of the current thread. Don't call the methods of a ''RunLoop'' object running in a different thread, which might cause unexpected results. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -46,28 +45,24 @@ namespace cocoon explicit RunLoop(Adopt adopt); /** * @brief Calls `-[NSRunLoop acceptInputForMode:beforeDate:]`. - * @details Runs the loop once or until the specified date, accepting input only for the specified mode. - Parameters: - mode: The mode in which to run. You may specify a custom mode or use one of the modes listed in ''RunLoop/Mode''. - limitDate: The date up until which to run. If no input sources or timers are attached to the run loop, this method exits immediately; otherwise, it runs the run loop once, returning as soon as one input source processes a message or the specified time elapses. > Note: > A timer is not considered an input source and may fire multiple times when waiting for this method to return. Manually removing all known input sources and timers from the run loop is not a guarantee that the run loop will exit. macOS can install and remove additional input sources as needed to process requests targeted at the receiver's thread. Those sources could therefore prevent the run loop from exiting. * @param mode Argument converted to the Objective-C parameter of the same role. * @param limit_date Argument converted to the Objective-C parameter of the same role. */ void accept_input_for_mode(const std::string& mode, const Date& limit_date) const; /** * @brief Calls `-[NSRunLoop addPort:forMode:]`. - * @details Adds a port as an input source to the specified mode of the run loop. - Parameters: - aPort: The port to add to the receiver. - mode: The mode in which to add the port. You may specify a custom mode or use one of the modes listed in ''RunLoop/Mode''. This method schedules the port with the receiver. You can add a port to multiple input modes. When the receiver is running in the specified mode, it dispatches messages destined for that port to the port's designated handler routine. * @param a_port Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void add_port(const Port& a_port, const std::string& mode) const; /** * @brief Calls `-[NSRunLoop addTimer:forMode:]`. - * @details Registers a given timer with a given input mode. - Parameters: - timer: The timer to register with the receiver. - mode: The mode in which to add the timer. You may specify a custom mode or use one of the modes listed in ''RunLoop/Mode''. You can add a timer to multiple input modes. While running in the designated mode, the receiver causes the timer to fire on or after its scheduled fire date. Upon firing, the timer invokes its associated handler routine, which is a selector on a designated object. The receiver retains 'aTimer'. To remove a timer from all run loop modes on which it is installed, send an ''Timer/invalidate()'' message to the timer. * @param timer Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void add_timer(const Timer& timer, const std::string& mode) const; /** * @brief Calls `-[NSRunLoop cancelPerformSelector:target:argument:]`. - * @details Cancels the sending of a previously scheduled message. - Parameters: - aSelector: The previously-specified selector. - target: The previously-specified target. - arg: The previously-specified argument. You can use this method to cancel a message previously scheduled with the ''RunLoop/perform(:target:argument:order:modes:)'' method. The parameters identify the message uniquely. This method removes the perform request from all modes of the run loop. * @param a_selector Argument converted to the Objective-C parameter of the same role. * @param target Argument converted to the Objective-C parameter of the same role. * @param arg Argument converted to the Objective-C parameter of the same role. @@ -75,19 +70,16 @@ namespace cocoon void cancel_perform_selector(const std::string& a_selector, const Object& target, const Object& arg) const; /** * @brief Calls `-[NSRunLoop cancelPerformSelectorsWithTarget:]`. - * @details Cancels all outstanding ordered performs scheduled with a given target. - Parameter target: The previously-specified target. This method cancels the previously scheduled messages associated with the target, ignoring the selector and argument of the scheduled operation. This is in contrast to ''RunLoop/cancelPerform(:target:argument:)'', which requires you to match the selector and argument as well as the target. This method removes the perform requests from all modes of the run loop. * @param target Argument converted to the Objective-C parameter of the same role. */ void cancel_perform_selectors_with_target(const Object& target) const; /** * @brief Calls `-[NSRunLoop getCFRunLoop]`. - * @details Returns the receiver's underlying 'CFRunLoop' object. You can use the returned run loop to configure the current run loop using Core Foundation function calls, for example, to set up a run loop observer. * @return The converted Objective-C result. */ CFRunLoop get_cf_run_loop() const; /** * @brief Calls `-[NSRunLoop limitDateForMode:]`. - * @details Performs one pass through the run loop in the specified mode and returns the date at which the next timer is scheduled to fire. - Parameter mode: The run loop mode to search. You may specify a custom mode or use one of the modes listed in ''RunLoop/Mode''. - Returns: The date at which the next timer is scheduled to fire, or 'nil' if there are no input sources for this mode. The run loop is entered with an immediate timeout, so the run loop does not block, waiting for input, if no input sources need processing. * @param mode Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -107,7 +99,6 @@ namespace cocoon void perform_in_modes(const std::vector& modes, std::function block) const; /** * @brief Calls `-[NSRunLoop performSelector:target:argument:order:modes:]`. - * @details Schedules the sending of a message on the receiver. - Parameters: - aSelector: A selector that identifies the method to invoke. The method should not have a significant return value and should take a single argument of type 'id'. - target: The object that defines the selector in 'aSelector'. - arg: The argument to pass to the method when it is performed. Pass 'nil' if the method does not take an argument. - order: The priority for the message. If multiple messages are scheduled, the messages with a lower order value are sent first. - modes: An array of input modes for which the message may be sent. You may specify custom modes or use one of the modes listed in ''RunLoop/Mode''. This method sets up a timer to perform the 'aSelector' message on the receiver at the start of the next run loop iteration, according to the specified modes. The timer is configured to run in the modes specified by the 'modes' parameter. When the timer fires, the thread attempts to dequeue the message from the run loop and perform the selector. It succeeds if the run loop is running and in one of the specified modes; otherwise, the timer waits until the run loop is in one of those modes. This method returns before the 'aSelector' message is sent. The receiver retains the 'target' and 'arg' objects until the timer for the selector fires, and then releases them as part of cleanup. Use this method if you want multiple messages to be sent after the current event has been processed and you want to make sure these messages are sent in a certain order. * @param a_selector Argument converted to the Objective-C parameter of the same role. * @param target Argument converted to the Objective-C parameter of the same role. * @param arg Argument converted to the Objective-C parameter of the same role. @@ -117,19 +108,16 @@ namespace cocoon void perform_selector(const std::string& a_selector, const Object& target, const Object& arg, std::uint64_t order, const std::vector& modes) const; /** * @brief Calls `-[NSRunLoop removePort:forMode:]`. - * @details Removes a port from the specified input mode of the run loop. - Parameters: - aPort: The port to remove from the receiver. - mode: The mode from which to remove the port. You may specify a custom mode or use one of the modes listed in ''RunLoop/Mode''. If you added the port to multiple input modes, you must remove it from each mode separately. * @param a_port Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void remove_port(const Port& a_port, const std::string& mode) const; /** * @brief Calls `-[NSRunLoop run]`. - * @details Puts the receiver into a permanent loop, during which time it processes data from all attached input sources. If no input sources or timers are attached to the run loop, this method exits immediately; otherwise, it runs the receiver in the ''RunLoop/Mode/default'' mode by repeatedly invoking ''RunLoop/run(mode:before:)''. In other words, this method effectively begins an infinite loop that processes data from the run loop's input sources and timers. Manually removing all known input sources and timers from the run loop is not a guarantee that the run loop will exit. macOS can install and remove additional input sources as needed to process requests targeted at the receiver's thread. Those sources could therefore prevent the run loop from exiting. If you want the run loop to terminate, you shouldn't use this method. Instead, use one of the other run methods and also check other arbitrary conditions of your own, in a loop. A simple example would be: '''objc BOOL shouldKeepRunning = YES; // global NSRunLoop theRL = [NSRunLoop currentRunLoop]; while (shouldKeepRunning && [theRL runMode:NSDefaultRunLoopMode beforeDate:[NSDate distantFuture]]); ''' */ void run() const; /** * @brief Calls `-[NSRunLoop runMode:beforeDate:]`. - * @details Runs the loop once, blocking for input in the specified mode until a given date. - Parameters: - mode: The mode in which to run. You may specify a custom mode or use one of the modes listed in ''RunLoop/Mode''. - limitDate: The date until which to block. - Returns: 'YES' if the run loop ran and processed an input source or if the specified timeout value was reached; otherwise, 'NO' if the run loop could not be started. If no input sources or timers are attached to the run loop, this method exits immediately and returns 'NO'; otherwise, it returns after either the first input source is processed or 'limitDate' is reached. > Note: > A timer is not considered an input source and may fire multiple times when waiting for this method to return. Manually removing all known input sources and timers from the run loop does not guarantee that the run loop will exit immediately. * @param mode Argument converted to the Objective-C parameter of the same role. * @param limit_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -137,25 +125,21 @@ namespace cocoon bool run_mode(const std::string& mode, const Date& limit_date) const; /** * @brief Calls `-[NSRunLoop runUntilDate:]`. - * @details Runs the loop until the specified date, during which time it processes data from all attached input sources. - Parameter limitDate: The date up until which to run. If no input sources or timers are attached to the run loop, this method exits immediately; otherwise, it runs the receiver in the ''RunLoop/Mode/default'' mode by repeatedly invoking ''RunLoop/run(mode:before:)'' until the specified expiration date. * @param limit_date Argument converted to the Objective-C parameter of the same role. */ void run_until_date(const Date& limit_date) const; /** * @brief Returns the `currentMode` property of `NSRunLoop`. - * @details The receiver's current input mode. This property contains the current input mode only while the receiver is running; otherwise, it returns 'nil'. The current mode is set by the methods that run the run loop, such as ''RunLoop/acceptInput(forMode:before:)'' and ''RunLoop/run(mode:before:)''. * @return The converted Objective-C result. */ std::string current_mode() const; /** * @brief Returns the `currentRunLoop` property of `NSRunLoop`. - * @details Returns the run loop for the current thread. If a run loop does not yet exist for the thread, one is created and returned. * @return The converted Objective-C result. */ static RunLoop current_run_loop(); /** * @brief Returns the `mainRunLoop` property of `NSRunLoop`. - * @details Returns the run loop of the main thread. * @return The converted Objective-C result. */ static RunLoop main_run_loop(); diff --git a/include/generated/save_panel.h b/include/generated/save_panel.h index 968df5cb..033c9cf0 100644 --- a/include/generated/save_panel.h +++ b/include/generated/save_panel.h @@ -259,13 +259,13 @@ namespace cocoon void set_prompt(const std::string& value) const; /** * @brief Returns the `showsContentTypes` property of `NSSavePanel`. - * @details Whether or not to show a popup list for selecting the type of the saved file. \@discussion The popup list shows the localized description for the types in 'allowedContentTypes'. To display a different description, implement the delegate method '-panel:displayNameForType:'. The default value is 'NO', do not show the content types. - Note: If 'allowedContentTypes' is empty, the control is not displayed. + * @details 'NSSavePanel': Whether or not to show a control for selecting the type of the saved file. The control shows the types in 'allowedContentTypes'. Default is 'NO'. 'NSOpenPanel': Not used. - Note: If 'allowedContentTypes' is empty, the control is not displayed. * @return The converted Objective-C result. */ bool shows_content_types() const; /** * @brief Sets the `showsContentTypes` property of `NSSavePanel`. - * @details Whether or not to show a popup list for selecting the type of the saved file. \@discussion The popup list shows the localized description for the types in 'allowedContentTypes'. To display a different description, implement the delegate method '-panel:displayNameForType:'. The default value is 'NO', do not show the content types. - Note: If 'allowedContentTypes' is empty, the control is not displayed. + * @details 'NSSavePanel': Whether or not to show a control for selecting the type of the saved file. The control shows the types in 'allowedContentTypes'. Default is 'NO'. 'NSOpenPanel': Not used. - Note: If 'allowedContentTypes' is empty, the control is not displayed. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_shows_content_types(bool value) const; diff --git a/include/generated/scanner.h b/include/generated/scanner.h index 8b21100e..4229c43d 100644 --- a/include/generated/scanner.h +++ b/include/generated/scanner.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSScanner` (Foundation). - * @details A string parser that scans for substrings or characters in a character set, and for numeric values from decimal, hexadecimal, and floating-point representations. A ''Scanner'' object interprets and converts the characters of a \ into number and string values. You assign the scanner's string when you create the scanner, and the scanner progresses through the characters of that string from beginning to end as you request items. Because of the nature of class clusters, a scanner object isn't an actual instance of the ''Scanner'' class, but is one of its private subclasses. Although a scanner object's class is private, its interface is public, as declared by this abstract superclass, ''Scanner''. The objects you create using this class are referred to as scanner objects (and when no confusion will result, merely as scanners). To set a ''Scanner'' object to ignore a set of characters as it scans the string, use the ''charactersToBeSkipped'' property. Characters in the skip set are skipped over before the target is scanned. The default set of characters to skip is the whitespace and newline character set. To retrieve the unscanned remainder of the string, use 'scanner.string.substring(from: scanner.scanLocation)'. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -49,14 +48,12 @@ namespace cocoon explicit Scanner(Adopt adopt); /** * @brief Calls `+[NSScanner localizedScannerWithString:]`. - * @details Returns an 'NSScanner' object that scans a given string according to the user's default locale. Sets the string to scan by invoking -initWithString: with 'aString'. The locale is set with the user's default locale. - Parameter string: The string to scan. - Returns: An 'NSScanner' object that scans 'aString' according to the user's default locale. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object localized_scanner_with_string(const std::string& string); /** * @brief Calls `-[NSScanner scanCharactersFromSet:intoString:]`. - * @details Scans the string as long as characters from a given character set are encountered, accumulating characters into a string that's returned by reference. Invoke this method with 'NULL' as 'stringValue' to simply scan past a given set of characters. - Parameters: - set: The set of characters to scan. - result: Upon return, contains the characters scanned. - Returns: 'YES' if the receiver scanned any characters, otherwise 'NO'. * @param set Argument converted to the Objective-C parameter of the same role. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -70,70 +67,60 @@ namespace cocoon bool scan_decimal(Decimal* dcm) const; /** * @brief Calls `-[NSScanner scanDouble:]`. - * @details Scans for a double value, returning a found value by reference. Skips past excess digits in the case of overflow, so the scanner's position is past the entire floating-point representation. Invoke this method with 'NULL' as 'doubleValue' to simply scan past a double value representation. Floating-point representations are assumed to be IEEE compliant. - Parameter result: Upon return, contains the scanned value. Contains 'HUGE_VAL' or '-HUGE_VAL' on overflow, or '0.0' on underflow. - Returns: 'YES' if the receiver finds a valid floating-point representation, otherwise 'NO'. Overflow or underflow are both considered valid floating-point representations. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_double(double* result) const; /** * @brief Calls `-[NSScanner scanFloat:]`. - * @details Scans for a float value, returning a found value by reference. Skips past excess digits in the case of overflow, so the scanner's position is past the entire floating-point representation. Invoke this method with 'NULL' as 'floatValue' to simply scan past a float value representation. Floating-point representations are assumed to be IEEE compliant. - Parameter result: Upon return, contains the scanned value. Contains 'HUGE_VAL' or '-HUGE_VAL' on overflow, or '0.0' on underflow. - Returns: 'YES' if the receiver finds a valid floating-point representation, otherwise 'NO'. Overflow or underflow are both considered valid floating-point representations. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_float(float* result) const; /** * @brief Calls `-[NSScanner scanHexDouble:]`. - * @details Scans for a double value from a hexadecimal representation, returning a found value by reference. This corresponds to '\%a' or '\%A' formatting. The hexadecimal double representation must be preceded by '0x' or '0X'. Skips past excess digits in the case of overflow, so the scanner's position is past the entire floating-point representation. Invoke this method with 'NULL' as 'result' to simply scan past a hexadecimal double representation. - Parameter result: Upon return, contains the scanned value. Contains 'HUGE_VAL' or '-HUGE_VAL' on overflow, or '0.0' on underflow. - Returns: 'YES' if the receiver finds a valid double-point representation, otherwise 'NO'. Overflow or underflow are both considered valid floating-point representations. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_hex_double(double* result) const; /** * @brief Calls `-[NSScanner scanHexFloat:]`. - * @details Scans for a double value from a hexadecimal representation, returning a found value by reference. This corresponds to '\%a' or '\%A' formatting. The hexadecimal float representation must be preceded by '0x' or '0X'. Skips past excess digits in the case of overflow, so the scanner's position is past the entire floating-point representation. Invoke this method with 'NULL' as 'result' to simply scan past a hexadecimal float representation. - Parameter result: Upon return, contains the scanned value. Contains 'HUGE_VAL' or '-HUGE_VAL' on overflow, or '0.0' on underflow. - Returns: 'YES' if the receiver finds a valid float-point representation, otherwise 'NO'. Overflow or underflow are both considered valid floating-point representations. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_hex_float(float* result) const; /** * @brief Calls `-[NSScanner scanHexInt:]`. - * @details Scans for an unsigned value from a hexadecimal representation, returning a found value by reference. The hexadecimal integer representation may optionally be preceded by '0x' or '0X'. Skips past excess digits in the case of overflow, so the receiver's position is past the entire hexadecimal representation. Invoke this method with 'NULL' as 'intValue' to simply scan past a hexadecimal integer representation. - Parameter result: Upon return, contains the scanned value. Contains 'UINT_MAX' on overflow. - Returns: 'YES' if the receiver finds a valid hexadecimal integer representation, otherwise 'NO'. Overflow is considered a valid hexadecimal integer representation. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_hex_int(unsigned int* result) const; /** * @brief Calls `-[NSScanner scanHexLongLong:]`. - * @details Scans for a long long value from a hexadecimal representation, returning a found value by reference. The hexadecimal integer representation may optionally be preceded by '0x' or '0X'. Skips past excess digits in the case of overflow, so the receiver's position is past the entire hexadecimal representation. Invoke this method with 'NULL' as 'result' to simply scan past a hexadecimal long long representation. - Parameter result: Upon return, contains the scanned value. Contains 'HUGE_VAL' or '-HUGE_VAL' on overflow. - Returns: 'YES' if the receiver finds a valid hexadecimal long long representation, otherwise 'NO'. Overflow is considered a valid hexadecimal long long representation. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_hex_long_long(std::uint64_t* result) const; /** * @brief Calls `-[NSScanner scanInt:]`. - * @details Scans for an int value from a decimal representation, returning a found value by reference. Skips past excess digits in the case of overflow, so the receiver's position is past the entire decimal representation. Invoke this method with 'NULL' as 'intValue' to simply scan past a decimal integer representation. - Parameter result: Upon return, contains the scanned value. Contains 'INT_MAX' or 'INT_MIN' on overflow. - Returns: 'YES' if the receiver finds a valid decimal integer representation, otherwise 'NO'. Overflow is considered a valid integer representation. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_int(int* result) const; /** * @brief Calls `-[NSScanner scanInteger:]`. - * @details Scans for an NSInteger value from a decimal representation, returning a found value by reference. Skips past excess digits in the case of overflow, so the receiver's position is past the entire integer representation. Invoke this method with 'NULL' as 'value' to simply scan past a decimal integer representation. - Parameter result: Upon return, contains the scanned value. Contains 'INT_MAX' or 'INT_MIN' on overflow. - Returns: 'YES' if the receiver finds a valid integer representation, otherwise 'NO'. Overflow is considered a valid integer representation. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_integer(std::int64_t* result) const; /** * @brief Calls `-[NSScanner scanLongLong:]`. - * @details Scans for a long long value from a decimal representation, returning a found value by reference. All overflow digits are skipped. Skips past excess digits in the case of overflow, so the receiver's position is past the entire decimal representation. Invoke this method with 'NULL' as 'longLongValue' to simply scan past a long decimal integer representation. - Parameter result: Upon return, contains the scanned value. Contains 'LLONG_MAX' or 'LLONG_MIN' on overflow. - Returns: 'YES' if the receiver finds a valid decimal integer representation, otherwise 'NO'. Overflow is considered a valid decimal integer representation. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_long_long(std::int64_t* result) const; /** * @brief Calls `-[NSScanner scanString:intoString:]`. - * @details Scans a given string, returning an equivalent string object by reference if a match is found. If 'string' is present at the current scan location, then the current scan location is advanced to after the string; otherwise the scan location does not change. Invoke this method with 'NULL' as 'stringValue' to simply scan past a given string. - Parameters: - string: The string for which to scan at the current scan location. - result: Upon return, if the receiver contains a string equivalent to 'string' at the current scan location, contains a string equivalent to 'string'. - Returns: 'YES' if 'string' matches the characters at the scan location, otherwise 'NO'. * @param string Argument converted to the Objective-C parameter of the same role. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -141,14 +128,12 @@ namespace cocoon bool scan_string(const std::string& string, std::string& result) const; /** * @brief Calls `-[NSScanner scanUnsignedLongLong:]`. - * @details Scans for an unsigned long long value from a decimal representation, returning a found value by reference. All overflow digits are skipped. Skips past excess digits in the case of overflow, so the receiver's position is past the entire decimal representation. Invoke this method with 'NULL' as 'unsignedLongLongValue' to simply scan past an unsigned long decimal integer representation. - Parameter result: Upon return, contains the scanned value. Contains 'ULLONG_MAX' on overflow. - Returns: 'YES' if the receiver finds a valid decimal integer representation, otherwise 'NO'. Overflow is considered a valid decimal integer representation. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool scan_unsigned_long_long(std::uint64_t* result) const; /** * @brief Calls `-[NSScanner scanUpToCharactersFromSet:intoString:]`. - * @details Scans the string until a character from a given character set is encountered, accumulating characters into a string that's returned by reference. Invoke this method with 'NULL' as 'stringValue' to simply scan up to a given set of characters. If no characters in 'stopSet' are present in the scanner's source string, the remainder of the source string is put into 'stringValue', the receiver's 'scanLocation' is advanced to the end of the source string, and the method returns 'YES'. - Parameters: - set: The set of characters up to which to scan. - result: Upon return, contains the characters scanned. - Returns: 'YES' if the receiver scanned any characters, otherwise 'NO'. If the only scanned characters are in the 'charactersToBeSkipped' character set (which is the whitespace and newline character set by default), then returns 'NO'. * @param set Argument converted to the Objective-C parameter of the same role. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -156,7 +141,6 @@ namespace cocoon bool scan_up_to_characters_from_set(const CharacterSet& set, std::string& result) const; /** * @brief Calls `-[NSScanner scanUpToString:intoString:]`. - * @details Scans the string until a given string is encountered, accumulating characters into a string that's returned by reference. If 'stopString' is present in the receiver, then on return the scan location is set to the beginning of that string. If 'stopString' is the first string in the receiver, then the method returns 'NO' and 'stringValue' is not changed. If the search string ('stopString') isn't present in the scanner's source string, the remainder of the source string is put into 'stringValue', the receiver's 'scanLocation' is advanced to the end of the source string, and the method returns 'YES'. Invoke this method with 'NULL' as 'stringValue' to simply scan up to a given string. - Parameters: - string: The string to scan up to. - result: Upon return, contains any characters that were scanned. - Returns: 'YES' if the receiver scans any characters, otherwise 'NO'. If the only scanned characters are in the 'charactersToBeSkipped' character set (which by default is the whitespace and newline character set), then this method returns 'NO'. * @param string Argument converted to the Objective-C parameter of the same role. * @param result Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -164,61 +148,51 @@ namespace cocoon bool scan_up_to_string(const std::string& string, std::string& result) const; /** * @brief Returns the `atEnd` property of `NSScanner`. - * @details Flag that indicates whether the receiver has exhausted all significant characters. 'YES' if the receiver has exhausted all significant characters in its string, otherwise 'NO'. If only characters from the set to be skipped remain, returns 'YES'. * @return The converted Objective-C result. */ bool is_at_end() const; /** * @brief Returns the `caseSensitive` property of `NSScanner`. - * @details Flag that indicates whether the receiver distinguishes case in the characters it scans. 'YES' if the receiver distinguishes case in the characters it scans, otherwise 'NO'. The default value is 'NO'. Note that case sensitivity doesn't apply to the characters to be skipped. * @return The converted Objective-C result. */ bool case_sensitive() const; /** * @brief Sets the `caseSensitive` property of `NSScanner`. - * @details Flag that indicates whether the receiver distinguishes case in the characters it scans. 'YES' if the receiver distinguishes case in the characters it scans, otherwise 'NO'. The default value is 'NO'. Note that case sensitivity doesn't apply to the characters to be skipped. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_case_sensitive(bool value) const; /** * @brief Returns the `charactersToBeSkipped` property of `NSScanner`. - * @details Character set containing the characters the scanner ignores when looking for a scannable element. Characters to be skipped are skipped prior to the scanner examining the target. For example, if a scanner ignores spaces and you send it a -scanInt: message, it skips spaces until it finds a decimal digit or other character. While an element is being scanned, no characters are skipped. If you scan for something made of characters in the set to be skipped (for example, using -scanInt: when the set of characters to be skipped is the decimal digits), the result is undefined. The characters to be skipped are treated as single values. A scanner doesn't apply its case sensitivity setting to these characters and doesn't attempt to match composed character sequences with anything in the set of characters to be skipped (though it does match pre-composed characters individually). If you want to skip all vowels while scanning a string, for example, you can set the characters to be skipped to those in the string "AEIOUaeiou" (plus any accented variants with pre-composed characters). The default set to skip is the whitespace and newline character set. * @return The converted Objective-C result. */ CharacterSet characters_to_be_skipped() const; /** * @brief Sets the `charactersToBeSkipped` property of `NSScanner`. - * @details Character set containing the characters the scanner ignores when looking for a scannable element. Characters to be skipped are skipped prior to the scanner examining the target. For example, if a scanner ignores spaces and you send it a -scanInt: message, it skips spaces until it finds a decimal digit or other character. While an element is being scanned, no characters are skipped. If you scan for something made of characters in the set to be skipped (for example, using -scanInt: when the set of characters to be skipped is the decimal digits), the result is undefined. The characters to be skipped are treated as single values. A scanner doesn't apply its case sensitivity setting to these characters and doesn't attempt to match composed character sequences with anything in the set of characters to be skipped (though it does match pre-composed characters individually). If you want to skip all vowels while scanning a string, for example, you can set the characters to be skipped to those in the string "AEIOUaeiou" (plus any accented variants with pre-composed characters). The default set to skip is the whitespace and newline character set. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_characters_to_be_skipped(const CharacterSet& value) const; /** * @brief Returns the `locale` property of `NSScanner`. - * @details The locale to use when scanning. A scanner's locale affects the way it interprets numeric values from the string. In particular, a scanner uses the locale's decimal separator to distinguish the integer and fractional parts of floating-point representations. A scanner with no locale set uses non-localized values. New scanners have no locale by default. * @return The converted Objective-C result. */ Object locale() const; /** * @brief Sets the `locale` property of `NSScanner`. - * @details The locale to use when scanning. A scanner's locale affects the way it interprets numeric values from the string. In particular, a scanner uses the locale's decimal separator to distinguish the integer and fractional parts of floating-point representations. A scanner with no locale set uses non-localized values. New scanners have no locale by default. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_locale(const Object& value) const; /** * @brief Returns the `scanLocation` property of `NSScanner`. - * @details The character position at which the receiver will begin its next scanning operation. Raises an 'NSRangeException' if 'index' is beyond the end of the string being scanned. This property is useful for backing up to rescan after an error. Rather than setting the scan location directly to skip known sequences of characters, use -scanString:intoString: or -scanCharactersFromSet:intoString:, which allow you to verify that the expected substring (or set of characters) is in fact present. * @return The converted Objective-C result. */ std::uint64_t scan_location() const; /** * @brief Sets the `scanLocation` property of `NSScanner`. - * @details The character position at which the receiver will begin its next scanning operation. Raises an 'NSRangeException' if 'index' is beyond the end of the string being scanned. This property is useful for backing up to rescan after an error. Rather than setting the scan location directly to skip known sequences of characters, use -scanString:intoString: or -scanCharactersFromSet:intoString:, which allow you to verify that the expected substring (or set of characters) is in fact present. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_scan_location(std::uint64_t value) const; /** * @brief Returns the `string` property of `NSScanner`. - * @details The string the scanner will scan. * @return The converted Objective-C result. */ std::string string() const; diff --git a/include/generated/screen.h b/include/generated/screen.h index 2cc743ab..78cc32b4 100644 --- a/include/generated/screen.h +++ b/include/generated/screen.h @@ -158,14 +158,6 @@ namespace cocoon * @return The converted Objective-C result. */ const WindowDepth* supported_window_depths() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `touchCapabilities` property of `NSScreen`. - * @return The converted Objective-C result. - */ - ScreenTouchCapabilities touch_capabilities() const; -#endif - /** * @brief Returns the `visibleFrame` property of `NSScreen`. * @return The converted Objective-C result. diff --git a/include/generated/script_class_description.h b/include/generated/script_class_description.h index de2daf62..706eeca3 100644 --- a/include/generated/script_class_description.h +++ b/include/generated/script_class_description.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSScriptClassDescription` (Foundation). - * @details A scriptable class that a macOS app supports. A scriptable application provides scriptability information that describes the commands and objects scripters can use in scripts that target the application. That includes information about the classes those scriptable objects are created from. An application's scriptability information is collected automatically by an instance of ''NSScriptSuiteRegistry''. The registry object creates an 'NSScriptClassDescription' for each class it finds and caches these objects in memory. Cocoa scripting uses registry information in handling scripting requests that target the application. A class description instance stores the name, attributes, relationships, and supported commands for a class. For example, a scriptable 'document' class for a drawing application might support attributes such as 'file' and 'file type', relationships such as collections of 'circles', 'rectangles', and 'lines', and commands such as 'align' and 'rotate'. As with many of the classes in Cocoa's built-in scripting support, your application may never need to directly work with instances of 'NSScriptClassDescription'. However, one case where you might need access to a class description is if you override 'objectSpecifier' in a scriptable class. For information on how to do this, see [Object Specifiers](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_object_specifiers/SAppsObjectSpecifiers.html\#//apple_ref/doc/uid/TP40002164-CH3) in [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html\#//apple_ref/doc/uid/TP40002164). Another case where your application may need access to class description information is if you override 'indicesOfObjectsByEvaluatingWithContainer:count:' in a specifier class. Although you can subclass 'NSScriptClassDescription', it is unlikely that you would need to do so, or even to create instances of it. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ClassDescription. * @@ -48,128 +47,124 @@ namespace cocoon using ClassDescription::class_description_for_class; /** * @brief Calls `-[NSScriptClassDescription appleEventCodeForKey:]`. - * @details Returns the Apple event code for the specified attribute or relationship in the receiver. - Parameter key: The identifying key for an attribute or relationship of the receiver. - Returns: The four-character Apple event code associated with the attribute or relationship identified by 'key' in the receiver or, if none exists, in the class description for the receiver's superclass. Returns '0' if no such attribute or relationship is found. + * @details Return the four character code that identifies the keyed attribute, to-one relationship, or to-many relationship in Apple events. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ unsigned int apple_event_code_for_key(const std::string& key) const; /** * @brief Calls `+[NSScriptClassDescription classDescriptionForClass:]`. - * @details Returns the class description for the specified class or, if it is not scriptable, for the first superclass that is. - Parameter aClass: The class whose description is needed. - Returns: The class description for the class specified by 'aClass' or, if that class isn't scriptable, the class description for the first superclass that is. Returns 'nil' if it doesn't find a scriptable class. + * @details Return the class description for a class or, if it is not scriptable, the first superclass that is. * @param a_class Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static ScriptClassDescription class_description_for_class(const std::string& a_class); /** * @brief Calls `-[NSScriptClassDescription classDescriptionForKey:]`. - * @details Returns the class description instance for the class type of the specified attribute or relationship. - Parameter key: The identifying key for an attribute or relationship of the receiver. - Returns: The instance of 'NSScriptClassDescription' for the type of the attribute or relationship specified by 'key'. Returns 'nil' if no scriptable property corresponds to 'key'. + * @details Return the class description for the keyed attribute, to-one relationship, or to-many relationship. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ScriptClassDescription class_description_for_key(const std::string& key) const; /** * @brief Calls `-[NSScriptClassDescription hasOrderedToManyRelationshipForKey:]`. - * @details Returns a Boolean value indicating whether the described class has an ordered to-many relationship identified by the specified key. - Parameter key: The identifying key for a property of the receiver. - Returns: 'true' if the described class has an ordered to-many relationship identified by the specified key; otherwise, 'false'. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool has_ordered_to_many_relationship_for_key(const std::string& key) const; /** * @brief Calls `-[NSScriptClassDescription hasPropertyForKey:]`. - * @details Returns a Boolean value indicating whether the described class has a property identified by the specified key. - Parameter key: The identifying key for a property of the receiver. - Returns: 'true' if the described class has a property identified by the specified key; otherwise, 'false'. + * @details Return whether the described class has a property identified by the key, whether it's a to-many relationship, whether it's readable, or whether it's writable, respectively. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool has_property_for_key(const std::string& key) const; /** * @brief Calls `-[NSScriptClassDescription hasReadablePropertyForKey:]`. - * @details Returns a Boolean value indicating whether the described class has a readable property identified by the specified key. To determine if a property is read-only, invoke ''NSScriptClassDescription/hasWritableProperty(forKey:)''. - Parameter key: The identifying key for a property of the receiver. - Returns: 'true' if the described class has a readable property identified by the specified key; otherwise, 'false'. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool has_readable_property_for_key(const std::string& key) const; /** * @brief Calls `-[NSScriptClassDescription hasWritablePropertyForKey:]`. - * @details Returns a Boolean value indicating whether the described class has a writable property identified by the specified key. - Parameter key: The identifying key for a property of the receiver. - Returns: 'true' if the described class has a writable property identified by the specified key; otherwise, 'false'. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool has_writable_property_for_key(const std::string& key) const; /** * @brief Calls `-[NSScriptClassDescription isLocationRequiredToCreateForKey:]`. - * @details Returns a Boolean value indicating whether an insertion location must be specified when creating a new object in the specified to-many relationship of the receiver. A script command object that creates a new object in a to-many relationship needs to know whether an explicitly specified insertion location is required. It can get this information from an instance of 'NSScriptClassDescription'. For example, 'NSMakeCommand' uses this method to determine whether or not a specific 'make' AppleScript command must have an 'at' parameter. - Parameter toManyRelationshipKey: The key for the to-many relationship that may require an insertion location. - Returns: 'true' if an insertion location must be specified; otherwise, 'false'. + * @details Return YES if creation of objects for the relationship specified by the key, in containers of the class described by the receiver, requires an explicitly specified insertion location. Return NO otherwise. For example, NSCreateCommand uses this method to determine whether or not a specific Make command must have an at parameter. * @param to_many_relationship_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_location_required_to_create_for_key(const std::string& to_many_relationship_key) const; /** * @brief Calls `-[NSScriptClassDescription keyWithAppleEventCode:]`. - * @details Given an Apple event code that identifies a property or element class, returns the key for the corresponding attribute, one-to-one relationship, or one-to-many relationship. - Parameter appleEventCode: An Apple event code that identifies a property or element class. - Returns: The key that corresponds to the property or element class identified by 'appleEventCode' in the receiver or, if none exists, in a class description in the receiver's superclasses. Returns 'nil' if it cannot find any such attribute or relationship. + * @details Given a four character code used to identify a property or element class in Apple events, return the key identifying the corresponding attribute, to-one relationship or to-many relationship. * @param apple_event_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string key_with_apple_event_code(unsigned int apple_event_code) const; /** * @brief Calls `-[NSScriptClassDescription matchesAppleEventCode:]`. - * @details Returns a Boolean value indicating whether a primary or secondary Apple event code in the receiver matches the passed code. - Parameter appleEventCode: An Apple event code to compare against the receiver's primary or secondary codes. - Returns: 'true' if the receiver's primary four-character Apple event code or any of its secondary codes (its synonyms) matches 'appleEventCode'; otherwise, 'false'. + * @details Return YES if the four character code identifies the described class in Apple events. Return NO otherwise. * @param apple_event_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool matches_apple_event_code(unsigned int apple_event_code) const; /** * @brief Calls `-[NSScriptClassDescription selectorForCommand:]`. - * @details Returns the selector associated with the receiver for the specified command description. If the described class or one of its superclasses is explicitly declared to support the described command and the declaration includes a method name, returns the selector for the class' handler method for the command. - Parameter commandDescription: A description for a script command, such as 'duplicate', 'make', or 'move'. Encapsulates the scriptability information for that command, such as its Objective-C selector, its argument names and types, and its return type (if any). - Returns: The selector from the receiver for the command specified by 'commandDescription'. Searches in the receiver first, then in any superclass. Returns 'NULL' if no matching selector is found. + * @details If the described class or one of its superclasses is explicitly declared to support the described command and the declaration includes a method name, return the selector for the class' handler method for the command. Return NULL otherwise. * @param command_description Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string selector_for_command(const ScriptCommandDescription& command_description) const; /** * @brief Calls `-[NSScriptClassDescription supportsCommand:]`. - * @details Returns a Boolean value indicating whether the receiver or any superclass supports the specified command. - Parameter commandDescription: A description for a script command, such as 'duplicate', 'make', or 'move'. Encapsulates the scriptability information for that command, such as its Objective-C selector, its argument names and types, and its return type (if any). - Returns: 'true' if the receiver or the instance of 'NSScriptClassDescription' of any superclass of the receiver's class lists the command described by 'commandDescription' among its supported commands; otherwise, 'false'. + * @details Return YES if the described class or one of its superclasses is explicitly declared to support the described command, NO otherwise. * @param command_description Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool supports_command(const ScriptCommandDescription& command_description) const; /** * @brief Calls `-[NSScriptClassDescription typeForKey:]`. - * @details Returns the name of the declared type of the attribute or relationship identified by the passed key. - Parameter key: The identifying key for an attribute, one-to-one relationship, or one-to-many relationship of the receiver. - Returns: The name of the declared type of the attribute or relationship identified by 'key'; for example, '"NSString"'. Searches in the receiver first, then in any superclass. Returns 'nil' if no match is found. + * @details Return the name of the declared type of the keyed attribute, to-one relationship, or to-many relationship. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string type_for_key(const std::string& key) const; /** * @brief Returns the `appleEventCode` property of `NSScriptClassDescription`. - * @details The Apple event code associated with the receiver's class. This is the primary four-character code used to identify the described class in Apple events. + * @details Return the primary four character code used to identify the described class in Apple events. * @return The converted Objective-C result. */ unsigned int apple_event_code() const; /** * @brief Returns the `className` property of `NSScriptClassDescription`. - * @details The name of the class the receiver describes, as provided at initialization time. This may be either the human-readable name for the class -- that is, the name that is used in a script -- or the name of the Objective-C class that is instantiated to implement the class. To reliably obtain the implementation name, use ''NSScriptClassDescription/implementationClassName''. * @return The converted Objective-C result. */ std::string class_name() const; /** * @brief Returns the `defaultSubcontainerAttributeKey` property of `NSScriptClassDescription`. - * @details The value of the 'DefaultSubcontainerAttribute' entry of the class declaration dictionary provided when the receiver was instantiated. Returns 'nil' if there was no such entry. + * @details Return the value of the DefaultSubcontainerAttribute entry of the class declaration dictionary provided when the receiver was instantiated, or nil if there was no such entry. * @return The converted Objective-C result. */ std::string default_subcontainer_attribute_key() const; /** * @brief Returns the `implementationClassName` property of `NSScriptClassDescription`. - * @details The name of the Objective-C class instantiated to implement the scripting class. The name returned by the ''NSScriptClassDescription/className'' property for an instance of 'NSScriptClassDescription' resulting from an sdef class declaration is the human-readable name for the class. To obtain the name of the Objective-C class instantiated to implement the class, use this property. + * @details Return the name of the Objective-C that implements the described scriptable class. * @return The converted Objective-C result. */ std::string implementation_class_name() const; /** * @brief Returns the `suiteName` property of `NSScriptClassDescription`. - * @details The name of the receiver's suite. Within an application's scriptability information, named suites contain related sets of information. + * @details Return the suite name or class name provided at initialization time. * @return The converted Objective-C result. */ std::string suite_name() const; /** * @brief Returns the `superclassDescription` property of `NSScriptClassDescription`. - * @details The class description instance for the superclass of the receiver's class. The instance of 'NSScriptClassDescription' that describes the superclass can be in the same suite as the receiver or in a different suite. Returns 'nil' if the class has no superclass. + * @details Return the scripting class description of the superclass of the class described by the receiver. * @return The converted Objective-C result. */ ScriptClassDescription superclass_description() const; diff --git a/include/generated/script_coercion_handler.h b/include/generated/script_coercion_handler.h index 9d8cde2d..ee4ffb02 100644 --- a/include/generated/script_coercion_handler.h +++ b/include/generated/script_coercion_handler.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSScriptCoercionHandler` (Foundation). - * @details A mechanism for converting one kind of scripting data to another. A shared instance of this class coerces (converts) object values to objects of another class using information supplied by classes that register with it. Coercions frequently are required during key-value coding. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -39,7 +38,6 @@ namespace cocoon explicit ScriptCoercionHandler(Adopt adopt); /** * @brief Calls `-[NSScriptCoercionHandler coerceValue:toClass:]`. - * @details Attempts to coerce the given value to the given class. * @param value Argument converted to the Objective-C parameter of the same role. * @param to_class Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -47,7 +45,6 @@ namespace cocoon Object coerce_value(const Object& value, const std::string& to_class) const; /** * @brief Calls `-[NSScriptCoercionHandler registerCoercer:selector:toConvertFromClass:toClass:]`. - * @details Registers a coercer to convert values from one class to another. The selector should take two arguments: the first is the value to be converted, and the second is the class to convert it to. The coercer should typically be a class object and the selector a factory method. * @param coercer Argument converted to the Objective-C parameter of the same role. * @param selector Argument converted to the Objective-C parameter of the same role. * @param from_class Argument converted to the Objective-C parameter of the same role. @@ -56,7 +53,6 @@ namespace cocoon void register_coercer(const Object& coercer, const std::string& selector, const std::string& from_class, const std::string& to_class) const; /** * @brief Calls `+[NSScriptCoercionHandler sharedCoercionHandler]`. - * @details Returns the shared coercion handler. * @return The converted Objective-C result. */ static ScriptCoercionHandler shared_coercion_handler(); diff --git a/include/generated/script_command.h b/include/generated/script_command.h index 9ec2ef1b..d5e9db4e 100644 --- a/include/generated/script_command.h +++ b/include/generated/script_command.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSScriptCommand` (Foundation). - * @details A self-contained scripting statement. An instance of ''NSScriptCommand'' represents a scripting statement, such as 'set word 5 of the front document to word 1 of the second document', and contains the information needed to perform the operation specified by the statement. When an Apple event reaches a Cocoa application, Cocoa's built-in scripting support transforms it into a script command (that is, an instance of 'NSScriptCommand' or one of the subclasses provided by Cocoa scripting or by your application) and executes the command in the context of the application. Executing a command means either invoking the selector associated with the command on the object or objects designated to receive the command, or having the command perform its default implementation method (''performDefaultImplementation()''). Your application most likely calls methods of 'NSScriptCommand' to extract the command arguments. You do this either in the 'performDefaultImplementation' method of a command subclass you have created, or in an object method designated as the selector to handle a particular command. As part of Cocoa's standard scripting implementation, 'NSScriptCommand' and its subclasses can handle the default command set for AppleScript's Standard suite for most applications without any subclassing. The Standard suite includes commands such as 'copy', 'count', 'create', 'delete', 'exists', and 'move', as well as common object classes such as 'application', 'document', and 'window'. For more information on working with script commands, see [Script Commands](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_script_cmds/SAppsScriptCmds.html\#//apple_ref/doc/uid/20001242) in [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html\#//apple_ref/doc/uid/TP40002164). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -54,144 +53,120 @@ namespace cocoon explicit ScriptCommand(Adopt adopt); /** * @brief Calls `+[NSScriptCommand currentCommand]`. - * @details Returns the currently executing script command, if any. If a command is being executed in the current thread by Cocoa Scripting's built-in Apple event handling, return the command. Return 'nil' otherwise. * @return The converted Objective-C result. */ static ScriptCommand current_command(); /** * @brief Calls `-[NSScriptCommand executeCommand]`. - * @details Evaluates the receiver specifier and arguments, validates the command, and executes it. If the command is valid and there are receivers, the command handler method for the receivers' class is invoked. If the command is valid but there are no receivers, 'performDefaultImplementation' is invoked. * @return The converted Objective-C result. */ Object execute_command() const; /** * @brief Calls `-[NSScriptCommand performDefaultImplementation]`. - * @details Overridden by subclasses to perform the default action for a command when no receivers explicitly handle it. If 'suspend' is invoked during the invocation of this method, its return value is ignored by Cocoa Scripting's built-in Apple event handling. * @return The converted Objective-C result. */ Object perform_default_implementation() const; /** * @brief Calls `-[NSScriptCommand resumeExecutionWithResult:]`. - * @details Resumes execution of a previously suspended command with a result. This method may be invoked in any thread, not just the one in which the corresponding invocation of 'suspendExecution' occurred. * @param result Argument converted to the Objective-C parameter of the same role. */ void resume_execution_with_result(const Object& result) const; /** * @brief Calls `-[NSScriptCommand suspendExecution]`. - * @details Suspends execution of this command. If the receiver is being executed in the current thread by Cocoa Scripting's built-in Apple event handling, suspend the execution of the command. A matching invocation of 'resumeExecutionWithResult:' must be made. */ void suspend_execution() const; /** * @brief Returns the `appleEvent` property of `NSScriptCommand`. - * @details The Apple event descriptor from which this command was constructed. Only available if the receiver was constructed by Cocoa Scripting's built-in Apple event handling. * @return The converted Objective-C result. */ AppleEventDescriptor apple_event() const; /** * @brief Returns the `arguments` property of `NSScriptCommand`. - * @details The arguments of the command. * @return The converted Objective-C result. */ std::map arguments() const; /** * @brief Sets the `arguments` property of `NSScriptCommand`. - * @details The arguments of the command. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_arguments(const std::map& value) const; /** * @brief Returns the `commandDescription` property of `NSScriptCommand`. - * @details The description of this script command. * @return The converted Objective-C result. */ ScriptCommandDescription command_description() const; /** * @brief Returns the `directParameter` property of `NSScriptCommand`. - * @details The object that corresponds to the direct parameter of the Apple event from which this command derives. * @return The converted Objective-C result. */ Object direct_parameter() const; /** * @brief Sets the `directParameter` property of `NSScriptCommand`. - * @details The object that corresponds to the direct parameter of the Apple event from which this command derives. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_direct_parameter(const Object& value) const; /** * @brief Returns the `evaluatedArguments` property of `NSScriptCommand`. - * @details The arguments of the command, with any object specifiers already evaluated. * @return The converted Objective-C result. */ std::map evaluated_arguments() const; /** * @brief Returns the `evaluatedReceivers` property of `NSScriptCommand`. - * @details If the direct parameter of the original event was an object specifier, returns the specified object or objects. Returns 'nil' if the direct parameter was not an object specifier or could not be evaluated. * @return The converted Objective-C result. */ Object evaluated_receivers() const; /** * @brief Returns the `receiversSpecifier` property of `NSScriptCommand`. - * @details The object specifier for the object or objects that will be given a chance to handle the command. If the direct parameter of the original event was an object specifier, 'setDirectParameter:' sends a 'setReceiversSpecifier:' message. * @return The converted Objective-C result. */ ScriptObjectSpecifier receivers_specifier() const; /** * @brief Sets the `receiversSpecifier` property of `NSScriptCommand`. - * @details The object specifier for the object or objects that will be given a chance to handle the command. If the direct parameter of the original event was an object specifier, 'setDirectParameter:' sends a 'setReceiversSpecifier:' message. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_receivers_specifier(const ScriptObjectSpecifier& value) const; /** * @brief Returns the `scriptErrorExpectedTypeDescriptor` property of `NSScriptCommand`. - * @details An 'NSAppleEventDescriptor' that identifies the expected type when a type mismatch error occurs. * @return The converted Objective-C result. */ AppleEventDescriptor script_error_expected_type_descriptor() const; /** * @brief Sets the `scriptErrorExpectedTypeDescriptor` property of `NSScriptCommand`. - * @details An 'NSAppleEventDescriptor' that identifies the expected type when a type mismatch error occurs. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_script_error_expected_type_descriptor(const AppleEventDescriptor& value) const; /** * @brief Returns the `scriptErrorNumber` property of `NSScriptCommand`. - * @details The error number associated with this command, if any. * @return The converted Objective-C result. */ std::int64_t script_error_number() const; /** * @brief Sets the `scriptErrorNumber` property of `NSScriptCommand`. - * @details The error number associated with this command, if any. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_script_error_number(std::int64_t value) const; /** * @brief Returns the `scriptErrorOffendingObjectDescriptor` property of `NSScriptCommand`. - * @details An 'NSAppleEventDescriptor' that identifies the offending object when an error occurs. * @return The converted Objective-C result. */ AppleEventDescriptor script_error_offending_object_descriptor() const; /** * @brief Sets the `scriptErrorOffendingObjectDescriptor` property of `NSScriptCommand`. - * @details An 'NSAppleEventDescriptor' that identifies the offending object when an error occurs. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_script_error_offending_object_descriptor(const AppleEventDescriptor& value) const; /** * @brief Returns the `scriptErrorString` property of `NSScriptCommand`. - * @details The error string associated with this command, if any. * @return The converted Objective-C result. */ std::string script_error_string() const; /** * @brief Sets the `scriptErrorString` property of `NSScriptCommand`. - * @details The error string associated with this command, if any. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_script_error_string(const std::string& value) const; /** * @brief Returns the `wellFormed` property of `NSScriptCommand`. - * @details A Boolean value that indicates whether the command is well-formed according to its command description. * @return The converted Objective-C result. */ bool is_well_formed() const; diff --git a/include/generated/script_command_description.h b/include/generated/script_command_description.h index 912c5380..fd4a4989 100644 --- a/include/generated/script_command_description.h +++ b/include/generated/script_command_description.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSScriptCommandDescription` (Foundation). - * @details A script command that a macOS app supports. A scriptable application provides scriptability information that describes the commands and objects scripters can use in scripts that target the application. An application's scripting information is collected automatically by an instance of ''NSScriptSuiteRegistry'', which creates an 'NSScriptCommandDescription' for each command it finds, caches these objects in memory, and installs a command handler for each command. A script command instance stores the name, class, argument types, and return type of a command. For example, commands in AppleScript's Core suite include 'clone', 'count', 'create', 'delete', 'exists', and 'move'. The public methods of 'NSScriptCommandDescription' are used primarily by Cocoa's built-in scripting support in responding to Apple events that target the application. Although you can subclass the 'NSScriptCommandDescription' class, it is unlikely that you would need to do so, or to create instances of it. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,76 +43,74 @@ namespace cocoon explicit ScriptCommandDescription(Adopt adopt); /** * @brief Calls `-[NSScriptCommandDescription appleEventCodeForArgumentWithName:]`. - * @details Returns the Apple event code for the specified command argument of the receiver. - Parameter argumentName: The argument name (used as a key) for which to obtain the corresponding Apple event code. - Returns: The code for the specified argument. + * @details Return the four character code that identifies in Apple events the declared type of the named argument in instances of the described command. * @param argument_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ unsigned int apple_event_code_for_argument_with_name(const std::string& argument_name) const; /** * @brief Calls `-[NSScriptCommandDescription createCommandInstance]`. - * @details Creates and returns an instance of the command object described by the receiver. - Returns: The command object, instantiated from ''NSScriptCommand'' or a subclass. + * @details Create an instance of the described command. * @return The converted Objective-C result. */ ScriptCommand create_command_instance() const; /** * @brief Calls `-[NSScriptCommandDescription isOptionalArgumentWithName:]`. - * @details Returns a Boolean value that indicates whether the command argument identified by the specified argument key is an optional argument. - Parameter argumentName: Argument name (used as a key) that identifies the command argument to examine. - Returns: 'true' if the specified argument exists and is optional; otherwise, 'false'. + * @details Return YES if the named argument is declared to be optional, NO otherwise. * @param argument_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_optional_argument_with_name(const std::string& argument_name) const; /** * @brief Calls `-[NSScriptCommandDescription typeForArgumentWithName:]`. - * @details Returns the type of the command argument identified by the specified key. - Parameter argumentName: Argument name (used as a key) that identifies the command argument to examine. - Returns: The type of the specified command argument. Returns 'nil' if there is no such argument. + * @details Return the declared type of the named argument in instances of the described command. * @param argument_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string type_for_argument_with_name(const std::string& argument_name) const; /** * @brief Returns the `appleEventClassCode` property of `NSScriptCommandDescription`. - * @details The four-character code for the Apple event class of the receiver's command. In an Apple event that specifies a script command, two four character codes -- the event class and event ID -- together identify the command. You use this property to obtain the event class. You use ''NSScriptCommandDescription/appleEventCode'' to obtain the event ID. For example, commands in AppleScript's Core suite, such as 'clone', 'count', and 'create', have an event class code of ''core''. This code and the event ID code returned by ''appleEventCode'' together specify the necessary information for identifying and dispatching an Apple event. + * @details Return the four character codes that identify the command in Apple events. * @return The converted Objective-C result. */ unsigned int apple_event_class_code() const; /** * @brief Returns the `appleEventCode` property of `NSScriptCommandDescription`. - * @details The four-character code for the Apple event ID of the receiver's command. This value, together with the event class code returned by ''NSScriptCommandDescription/appleEventClassCode'', specifies the necessary information for identifying and dispatching an Apple event. * @return The converted Objective-C result. */ unsigned int apple_event_code() const; /** * @brief Returns the `appleEventCodeForReturnType` property of `NSScriptCommandDescription`. - * @details The Apple event code that identifies the command's return type. + * @details Return the four character code that identifies in Apple events the declared type of the result of execution of the described command. * @return The converted Objective-C result. */ unsigned int apple_event_code_for_return_type() const; /** * @brief Returns the `argumentNames` property of `NSScriptCommandDescription`. - * @details The names (or keys) for all arguments of the receiver's command. If there are no arguments for the command, returns an empty array. + * @details Return the strings valid for use as keys into argument dictionaries in instances of the described command. * @return The converted Objective-C result. */ std::vector argument_names() const; /** * @brief Returns the `commandClassName` property of `NSScriptCommandDescription`. - * @details The name of the class that will be instantiated to handle the command. The Objective-C class name (for example, '"NSGetCommand"'). This is always ''NSScriptCommand'' or a subclass. + * @details Return the Objective-C class name for instances of the described command. * @return The converted Objective-C result. */ std::string command_class_name() const; /** * @brief Returns the `commandName` property of `NSScriptCommandDescription`. - * @details The name of the command. The command name as it appears in the application's scriptability information; may be different from what is displayed to the scripter. * @return The converted Objective-C result. */ std::string command_name() const; /** * @brief Returns the `returnType` property of `NSScriptCommandDescription`. - * @details The return type of the command. The receiver's command return type (for example, '"NSNumber"' or '"NSDictionary"'), or 'nil' if the described command is not declared to return a result. + * @details Return the declared type name for the result of execution of the described command, or nil if the described command is not declared to return a result. * @return The converted Objective-C result. */ std::string return_type() const; /** * @brief Returns the `suiteName` property of `NSScriptCommandDescription`. - * @details The name of the suite that contains the command described by the receiver. Within an application's scriptability information, named suites contain related sets of information. + * @details Return the suite name or command name provided at initialization time. * @return The converted Objective-C result. */ std::string suite_name() const; diff --git a/include/generated/script_execution_context.h b/include/generated/script_execution_context.h index 28a25292..d84acb69 100644 --- a/include/generated/script_execution_context.h +++ b/include/generated/script_execution_context.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSScriptExecutionContext` (Foundation). - * @details The context in which the current script command is executed. An 'NSScriptExecutionContext' object is a shared instance (there is only one instance of the class) that represents the context in which the current script command is executed. 'NSScriptExecutionContext' tracks global state relating to the command being executed, especially the top-level container object (that is, the container implied by a specifier object that specifies no container) used in an evaluation of an ''NSScriptObjectSpecifier'' object. In most cases, the top-level container for a complete series of nested object specifiers is automatically set to the application object ('NSApp'), and you can get this object with the ''topLevelObject'' method. But you can also set this top-level container to something else (using ''topLevelObject'') if the situation warrants it. It is unlikely that you will need to subclass 'NSScriptExecutionContext'. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -39,43 +38,36 @@ namespace cocoon explicit ScriptExecutionContext(Adopt adopt); /** * @brief Calls `+[NSScriptExecutionContext sharedScriptExecutionContext]`. - * @details Returns the shared script execution context. * @return The converted Objective-C result. */ static ScriptExecutionContext shared_script_execution_context(); /** * @brief Returns the `objectBeingTested` property of `NSScriptExecutionContext`. - * @details The object currently being tested by an 'NSWhoseSpecifier'. * @return The converted Objective-C result. */ Object object_being_tested() const; /** * @brief Sets the `objectBeingTested` property of `NSScriptExecutionContext`. - * @details The object currently being tested by an 'NSWhoseSpecifier'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_object_being_tested(const Object& value) const; /** * @brief Returns the `rangeContainerObject` property of `NSScriptExecutionContext`. - * @details The container object for the current range specifier being evaluated. * @return The converted Objective-C result. */ Object range_container_object() const; /** * @brief Sets the `rangeContainerObject` property of `NSScriptExecutionContext`. - * @details The container object for the current range specifier being evaluated. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_range_container_object(const Object& value) const; /** * @brief Returns the `topLevelObject` property of `NSScriptExecutionContext`. - * @details The top-level object in the current scripting context. * @return The converted Objective-C result. */ Object top_level_object() const; /** * @brief Sets the `topLevelObject` property of `NSScriptExecutionContext`. - * @details The top-level object in the current scripting context. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_top_level_object(const Object& value) const; diff --git a/include/generated/script_object_specifier.h b/include/generated/script_object_specifier.h index 2382e9a1..b8bf9320 100644 --- a/include/generated/script_object_specifier.h +++ b/include/generated/script_object_specifier.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSScriptObjectSpecifier` (Foundation). - * @details An abstract class used to represent natural language expressions. 'NSScriptObjectSpecifier' is the abstract superclass for classes that instantiate objects called "object specifiers." An object specifier represents an AppleScript reference form, which is a natural-language expression such as 'words 10 through 20' or 'front document' or 'words whose color is red'. The scripting system maps these words or phrases to attributes and relationships of scriptable objects. A reference form rarely occurs in isolation; usually a script statement consists of a series of reference forms preceded by a command and typically connected to each other by 'of', such as: '''objc get words whose color is blue of paragraph 10 of front document ''' The expression 'words whose color is blue of paragraph 10 of front document' specifies a location in the application's AppleScript object model—the objects the application makes available to scripters. The classes of objects in the object model often closely match the classes of actual objects in the application, but they are not required to. An object specifier locates objects in the running application that correspond to the specified object model objects. Your application typically creates object specifiers when it implements the 'objectSpecifier' method for its scriptable classes. That method is defined by the NSScriptObjectSpecifiers protocol. It is unlikely that you would ever need to create your own subclass of 'NSScriptObjectSpecifier'; the set of valid AppleScript reference forms is determined by Apple Computer and object specifier classes are already implemented for this set. If for some reason you do need to create a subclass, you must override the primitive method ''indicesOfObjectsByEvaluating(withContainer:count:)'' to return indices to the elements within the container whose values are matched with the child specifier's key. In addition, you probably need to declare any special instance variables and implement an initializer that invokes super's designated initializer, ''init(containerClassDescription:containerSpecifier:key:)'', and initializes these variables. For a comprehensive treatment of object specifiers, including sample code, see [Object Specifiers](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_object_specifiers/SAppsObjectSpecifiers.html\#//apple_ref/doc/uid/TP40002164-CH3) in [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html\#//apple_ref/doc/uid/TP40002164). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -53,7 +52,6 @@ namespace cocoon explicit ScriptObjectSpecifier(Adopt adopt); /** * @brief Calls `-[NSScriptObjectSpecifier indicesOfObjectsByEvaluatingWithContainer:count:]`. - * @details Returns the indices of the specified objects in the container. * @param container Argument converted to the Objective-C parameter of the same role. * @param count Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -61,123 +59,105 @@ namespace cocoon std::int64_t* indices_of_objects_by_evaluating_with_container(const Object& container, std::int64_t* count) const; /** * @brief Calls `+[NSScriptObjectSpecifier objectSpecifierWithDescriptor:]`. - * @details Given a 'typeObjectSpecifier' Apple event descriptor, creates and returns an object specifier. Returns 'nil' on failure. If this is invoked and fails during the execution of a script command, information about the error that caused the failure is recorded in '[NSScriptCommand currentCommand]'. + * @details Given a typeObjectSpecifier Apple event descriptor, create and return an object specifier, or nil for failure. If this is invoked and fails during the execution of a script command, information about the error that caused the failure is recorded in [NSScriptCommand currentCommand]. * @param descriptor Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static ScriptObjectSpecifier object_specifier_with_descriptor(const AppleEventDescriptor& descriptor); /** * @brief Calls `-[NSScriptObjectSpecifier objectsByEvaluatingWithContainers:]`. - * @details Returns the specified objects from the given containers. * @param containers Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object objects_by_evaluating_with_containers(const Object& containers) const; /** * @brief Returns the `childSpecifier` property of `NSScriptObjectSpecifier`. - * @details The child specifier of this specifier. * @return The converted Objective-C result. */ ScriptObjectSpecifier child_specifier() const; /** * @brief Sets the `childSpecifier` property of `NSScriptObjectSpecifier`. - * @details The child specifier of this specifier. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_child_specifier(const ScriptObjectSpecifier& value) const; /** * @brief Returns the `containerClassDescription` property of `NSScriptObjectSpecifier`. - * @details The class description for the container. * @return The converted Objective-C result. */ ScriptClassDescription container_class_description() const; /** * @brief Sets the `containerClassDescription` property of `NSScriptObjectSpecifier`. - * @details The class description for the container. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_container_class_description(const ScriptClassDescription& value) const; /** * @brief Returns the `containerIsObjectBeingTested` property of `NSScriptObjectSpecifier`. - * @details A Boolean value that indicates whether the container is the object currently being tested by an 'NSWhoseSpecifier'. * @return The converted Objective-C result. */ bool container_is_object_being_tested() const; /** * @brief Sets the `containerIsObjectBeingTested` property of `NSScriptObjectSpecifier`. - * @details A Boolean value that indicates whether the container is the object currently being tested by an 'NSWhoseSpecifier'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_container_is_object_being_tested(bool value) const; /** * @brief Returns the `containerIsRangeContainerObject` property of `NSScriptObjectSpecifier`. - * @details A Boolean value that indicates whether the container is the container for the current range specifier being evaluated. * @return The converted Objective-C result. */ bool container_is_range_container_object() const; /** * @brief Sets the `containerIsRangeContainerObject` property of `NSScriptObjectSpecifier`. - * @details A Boolean value that indicates whether the container is the container for the current range specifier being evaluated. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_container_is_range_container_object(bool value) const; /** * @brief Returns the `containerSpecifier` property of `NSScriptObjectSpecifier`. - * @details The container specifier of this specifier. * @return The converted Objective-C result. */ ScriptObjectSpecifier container_specifier() const; /** * @brief Sets the `containerSpecifier` property of `NSScriptObjectSpecifier`. - * @details The container specifier of this specifier. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_container_specifier(const ScriptObjectSpecifier& value) const; /** * @brief Returns the `descriptor` property of `NSScriptObjectSpecifier`. - * @details An Apple event descriptor that represents this specifier. + * @details Return an Apple event descriptor that represents the receiver. If the receiver was created with +objectSpecifierWithDescriptor: that passed-in descriptor is returned. Otherwise a new one is created and returned (autoreleased, of course). * @return The converted Objective-C result. */ AppleEventDescriptor descriptor() const; /** * @brief Returns the `evaluationErrorNumber` property of `NSScriptObjectSpecifier`. - * @details The error number from the most recent evaluation. * @return The converted Objective-C result. */ std::int64_t evaluation_error_number() const; /** * @brief Sets the `evaluationErrorNumber` property of `NSScriptObjectSpecifier`. - * @details The error number from the most recent evaluation. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_evaluation_error_number(std::int64_t value) const; /** * @brief Returns the `evaluationErrorSpecifier` property of `NSScriptObjectSpecifier`. - * @details The specifier in which an evaluation error occurred. * @return The converted Objective-C result. */ ScriptObjectSpecifier evaluation_error_specifier() const; /** * @brief Returns the `key` property of `NSScriptObjectSpecifier`. - * @details The name of the key in the container object to be accessed by this specifier. * @return The converted Objective-C result. */ std::string key() const; /** * @brief Sets the `key` property of `NSScriptObjectSpecifier`. - * @details The name of the key in the container object to be accessed by this specifier. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_key(const std::string& value) const; /** * @brief Returns the `keyClassDescription` property of `NSScriptObjectSpecifier`. - * @details The class description for the keyed objects. * @return The converted Objective-C result. */ ScriptClassDescription key_class_description() const; /** * @brief Returns the `objectsByEvaluatingSpecifier` property of `NSScriptObjectSpecifier`. - * @details The actual objects represented by this specifier. * @return The converted Objective-C result. */ Object objects_by_evaluating_specifier() const; diff --git a/include/generated/script_suite_registry.h b/include/generated/script_suite_registry.h index 38e10664..1ff6ac8f 100644 --- a/include/generated/script_suite_registry.h +++ b/include/generated/script_suite_registry.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSScriptSuiteRegistry` (Foundation). - * @details The top-level repository of scriptability information for an app at runtime. Scriptability information specifies the terminology available for use in scripts that target an application. It also provides information, used by AppleScript and by Cocoa, about how support for that terminology is implemented in the application. This information includes descriptions of the scriptable object classes in an application and of the commands the application supports. There are two standard formats for supplying scriptability information: the older script suite format, consisting of a script suite file and one or more script terminology files, and the newer scripting definition (or sdef) format, consisting of a single sdef file. There is one instance of 'NSScriptSuiteRegistry' per scriptable application. This registry object collects scriptability information when the application first needs to respond to an Apple event for which Cocoa hasn't installed a default event handler. It then creates one instance of ''NSScriptClassDescription'' for each object class and one instance of ''NSScriptCommandDescription'' for each command class, and installs a command handler for each command. When a user executes an AppleScript script, Apple events are sent to the targeted application. Using the information stored in the registry object, Cocoa automatically converts incoming Apple events into script commands (based on ''NSScriptCommand'' or a subclass) that manipulate objects in the application. The public methods of 'NSScriptSuiteRegistry' are used primarily by Cocoa's built-in scripting support. You should not need to create a subclass of 'NSScriptSuiteRegistry'. For information on scriptability information formats, loading of scriptability information, and related topics, see "Scriptability Information" in [Overview of Cocoa Support for Scriptable Applications](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_about_apps/SAppsAboutApps.html\#//apple_ref/doc/uid/TP40001976) in [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html\#//apple_ref/doc/uid/TP40002164). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -46,42 +45,42 @@ namespace cocoon explicit ScriptSuiteRegistry(Adopt adopt); /** * @brief Calls `-[NSScriptSuiteRegistry aeteResource:]`. - * @details Returns an 'NSData' object that contains data in ''aete'' resource format describing the scriptability information currently known to the application. This method is typically invoked to implement the 'get aete' Apple event for an application that provides scriptability information in the script suite format. The 'languageName' argument is the name of a language for which a localized resource directory (such as 'English.lproj') exists. This language indication specifies the set of '.scriptTerminology' files to be used to generate the data. 'NSScriptSuiteRegistry' does not create an ''aete'' resource unless this method is called. - Parameter languageName: The name of a language for which localized script terminology files exist. - Returns: Data in ''aete'' resource format, or 'nil' if the data cannot be generated. + * @details Return suitable reply data for the standard Get AETE Apple event, given the set of scripting suites currently registered. * @param language_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector aete_resource(const std::string& language_name) const; /** * @brief Calls `-[NSScriptSuiteRegistry appleEventCodeForSuite:]`. - * @details Returns the Apple event code associated with the suite named 'suiteName', such as ''core'' for the Core suite. - Parameter suiteName: The name of a scripting suite. - Returns: The four-character code used to identify the named suite. + * @details Return the four character code used to identify the named suite. * @param suite_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ unsigned int apple_event_code_for_suite(const std::string& suite_name) const; /** * @brief Calls `-[NSScriptSuiteRegistry bundleForSuite:]`. - * @details Returns the bundle containing the suite-definition property list (extension '.scriptSuite') identified by 'suiteName'. - Parameter suiteName: The name of a scripting suite. - Returns: The bundle that contains the code that implements the named suite. + * @details Return the bundle that contains the code that implements the named suite. * @param suite_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Bundle bundle_for_suite(const std::string& suite_name) const; /** * @brief Calls `-[NSScriptSuiteRegistry classDescriptionWithAppleEventCode:]`. - * @details Returns the class description associated with the given four-character Apple event code, 'appleEventCode'. Overriding behavior is important here. Multiple classes can have the same code if the classes have an uninterrupted linear inheritance from one another. For example, if class B is a subclass of A and class C is a subclass of B, and all three classes have the same four-character Apple event code, then this method returns the class description for class C. - Parameter appleEventCode: A four-character code used to identify a scriptable class in Apple events. - Returns: The class description, or 'nil' if no class matches. + * @details Given a four character code used to identify a scriptable class in Apple events, return the class description. * @param apple_event_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ScriptClassDescription class_description_with_apple_event_code(unsigned int apple_event_code) const; /** * @brief Calls `-[NSScriptSuiteRegistry classDescriptionsInSuite:]`. - * @details Returns the class descriptions contained in the suite identified by 'suiteName'. Each class description (instance of ''NSScriptClassDescription'') in the returned dictionary is identified by class name. - Parameter suiteName: The name of a scripting suite. - Returns: A dictionary containing the descriptions of all of the classes in the named suite, keyed by class name. + * @details Return a dictionary containing the descriptions of all of the classes or commands in the named suite, keyed by class or comand name. * @param suite_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map class_descriptions_in_suite(const std::string& suite_name) const; /** * @brief Calls `-[NSScriptSuiteRegistry commandDescriptionWithAppleEventClass:andAppleEventCode:]`. - * @details Returns the command description identified by a suite's four-character Apple event code of the class and the four-character Apple event code of the command. - Parameters: - appleEventClassCode: The four-character Apple event class code. - appleEventIDCode: The four-character Apple event ID code. - Returns: The command description, or 'nil' if no command matches. + * @details Given the pair of four character codes used to identify a scripting command in Apple events, return the command description. * @param apple_event_class_code Argument converted to the Objective-C parameter of the same role. * @param apple_event_id_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -89,58 +88,55 @@ namespace cocoon ScriptCommandDescription command_description_with_apple_event_class(unsigned int apple_event_class_code, unsigned int apple_event_id_code) const; /** * @brief Calls `-[NSScriptSuiteRegistry commandDescriptionsInSuite:]`. - * @details Returns the command descriptions contained in the suite identified by 'suiteName'. Each command description (instance of ''NSScriptCommandDescription'') in the returned dictionary is identified by command name. - Parameter suiteName: The name of a scripting suite. - Returns: A dictionary containing the descriptions of all of the commands in the named suite, keyed by command name. * @param suite_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map command_descriptions_in_suite(const std::string& suite_name) const; /** * @brief Calls `-[NSScriptSuiteRegistry loadSuiteWithDictionary:fromBundle:]`. - * @details Loads the suite definition encapsulated in 'suiteDeclaration'; previously, this suite definition was parsed from a '.scriptSuite' property list contained in a framework or in 'bundle'. The method extracts information from the dictionary and caches it in various internal collection objects. If keys are missing or values are of the wrong type, it logs messages to the console. It also registers class descriptions and command descriptions. In registering a class description, it invokes the ''NSClassDescription'' class method ''NSClassDescription/register(:for:)''. In registering a command description, it arranges for the Apple event translator to handle incoming Apple events that represent the defined commands. This method is invoked when the shared instance is initialized and when bundles are loaded at runtime. Prior to invoking it, 'NSScriptSuiteRegistry' creates the dictionary argument from the '.scriptSuite' property list. If you invoke this method in your code, you should try to do it before the application receives its first Apple event. - Parameters: - suiteDeclaration: A scripting suite declaration dictionary of the sort that is valid in '.scriptSuite' property list files. - bundle: The bundle that contains the code that implements the suite. + * @details Given a scripting suite declaration dictionary of the sort that is valid in .scriptSuite property list files, and a pointer to the bundle that contains the code that implements the suite, register class and command descriptions for the suite. * @param suite_declaration Argument converted to the Objective-C parameter of the same role. * @param bundle Argument converted to the Objective-C parameter of the same role. */ void load_suite_with_dictionary(const std::vector>& suite_declaration, const Bundle& bundle) const; /** * @brief Calls `-[NSScriptSuiteRegistry loadSuitesFromBundle:]`. - * @details Loads the suite definitions in the specified bundle, invoking ''NSScriptSuiteRegistry/loadSuite(with:from:)'' for each suite found. If errors occur while the method is parsing a suite-definition file, the method logs error messages to the console. Redundant invocations of this method are ignored. - Parameter bundle: The bundle from which to load '.scriptSuite'/'.scriptTerminology' resource files. + * @details Given a bundle, register class and command descriptions from any .scriptSuite/.scriptTerminology resource files in the bundle. Redundant invocations of this method are ignored. * @param bundle Argument converted to the Objective-C parameter of the same role. */ void load_suites_from_bundle(const Bundle& bundle) const; /** * @brief Calls `-[NSScriptSuiteRegistry registerClassDescription:]`. - * @details Registers class description 'classDescription' for use by Cocoa's built-in scripting support by storing it in a per-suite internal dictionary under the class name. - Parameter classDescription: The scripting class description to register. + * @details Register a scripting class or command description. * @param class_description Argument converted to the Objective-C parameter of the same role. */ void register_class_description(const ScriptClassDescription& class_description) const; /** * @brief Calls `-[NSScriptSuiteRegistry registerCommandDescription:]`. - * @details Registers command description 'commandDescription' for use by Cocoa's built-in scripting support by storing it in a per-suite internal dictionary under the command name. Also registers with the single, shared instance of ''NSAppleEventManager'' to handle incoming Apple events that should be handled by the command. - Parameter commandDescription: The scripting command description to register. * @param command_description Argument converted to the Objective-C parameter of the same role. */ void register_command_description(const ScriptCommandDescription& command_description) const; /** * @brief Calls `+[NSScriptSuiteRegistry setSharedScriptSuiteRegistry:]`. - * @details Sets the single, shared instance of 'NSScriptSuiteRegistry' to 'registry'. * @param registry Argument converted to the Objective-C parameter of the same role. */ static void set_shared_script_suite_registry(const ScriptSuiteRegistry& registry); /** * @brief Calls `+[NSScriptSuiteRegistry sharedScriptSuiteRegistry]`. - * @details Returns the single, shared instance of 'NSScriptSuiteRegistry', creating it first if it doesn't exist. If it creates an instance, and if the application provides scriptability information in the script suite format, the method loads suite definitions in all frameworks and other bundles that the application currently imports or includes; if information is provided in the sdef format, the method loads information only from the specified sdef file. If in reading scriptability information an exception is raised because of parsing errors, it handles the exception by printing a line of information to the console. + * @details Get or set the program's single NSScriptSuiteRegistry. * @return The converted Objective-C result. */ static ScriptSuiteRegistry shared_script_suite_registry(); /** * @brief Calls `-[NSScriptSuiteRegistry suiteForAppleEventCode:]`. - * @details Returns the name of the suite definition associated with the given four-character Apple event code, 'appleEventCode'. - Parameter appleEventCode: A four-character code used to identify a scripting suite. - Returns: The name of the suite, or 'nil' if no suite matches. + * @details Given a four character code used to identify a scripting suite, return the name of the suite. * @param apple_event_code Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string suite_for_apple_event_code(unsigned int apple_event_code) const; /** * @brief Returns the `suiteNames` property of `NSScriptSuiteRegistry`. - * @details The names of the suite definitions currently loaded by the application. + * @details Return a list of all registered suite names. * @return The converted Objective-C result. */ std::vector suite_names() const; diff --git a/include/generated/script_whose_test.h b/include/generated/script_whose_test.h index 8391545c..62603644 100644 --- a/include/generated/script_whose_test.h +++ b/include/generated/script_whose_test.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSScriptWhoseTest` (Foundation). - * @details An abstract class that provides the basis for testing specifiers one at a time or in groups. 'NSScriptWhoseTest' is an abstract class whose sole method is ''isTrue()''. Two concrete subclasses of 'NSScriptWhoseTest' generate objects representing Boolean expressions comparing one object with another and objects representing multiple Boolean expressions connected by logical operators ('OR', 'AND', 'NOT'). These classes are, respectively, ''NSSpecifierTest'' and ''NSLogicalTest''. In evaluating itself, an ''NSWhoseSpecifier'' invokes the ''isTrue()'' method of its "test" object. You shouldn't need to subclass 'NSScriptWhoseTest', and you should rarely need to subclass one of its subclasses. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -39,7 +38,6 @@ namespace cocoon explicit ScriptWhoseTest(Adopt adopt); /** * @brief Calls `-[NSScriptWhoseTest isTrue]`. - * @details Returns a Boolean value that indicates whether this test evaluates to true. * @return The converted Objective-C result. */ bool is_true() const; diff --git a/include/generated/scroll_view.h b/include/generated/scroll_view.h index 2c396603..baae8f0d 100644 --- a/include/generated/scroll_view.h +++ b/include/generated/scroll_view.h @@ -12,8 +12,6 @@ namespace cocoon class Color; class Cursor; class Event; - class GestureRecognizer; - class RefreshController; class RulerView; class Scroller; class View; @@ -376,24 +374,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_max_magnification(double value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `maximumNumberOfTouchesForScrolling` property of `NSScrollView`. - * @details The maximum number of touches needed for scrolling Set this property to 0 to require exactly 'minimumNumberOfTouchesForScrolling' touches to recognize the gesture. Defaults to 'NSIntegerMax'. - * @return The converted Objective-C result. - */ - std::int64_t maximum_number_of_touches_for_scrolling() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `maximumNumberOfTouchesForScrolling` property of `NSScrollView`. - * @details The maximum number of touches needed for scrolling Set this property to 0 to require exactly 'minimumNumberOfTouchesForScrolling' touches to recognize the gesture. Defaults to 'NSIntegerMax'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_maximum_number_of_touches_for_scrolling(std::int64_t value) const; -#endif - /** * @brief Returns the `minMagnification` property of `NSScrollView`. * @details This value determines how small the content can be magnified. The default value is 0.25. @@ -406,24 +386,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_min_magnification(double value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `minimumNumberOfTouchesForScrolling` property of `NSScrollView`. - * @details The minimum number of touches needed for scrolling Defaults to 1. - * @return The converted Objective-C result. - */ - std::int64_t minimum_number_of_touches_for_scrolling() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `minimumNumberOfTouchesForScrolling` property of `NSScrollView`. - * @details The minimum number of touches needed for scrolling Defaults to 1. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_minimum_number_of_touches_for_scrolling(std::int64_t value) const; -#endif - /** * @brief Returns the `pageScroll` property of `NSScrollView`. * @return The converted Objective-C result. @@ -434,24 +396,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_page_scroll(double value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `refreshController` property of `NSScrollView`. - * @details The refresh controller associated with this scroll view. Setting this property adds the refresh controller to the scroll view, enabling pull-to-refresh functionality. Set to nil to remove it. - * @return The converted Objective-C result. - */ - RefreshController refresh_controller() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `refreshController` property of `NSScrollView`. - * @details The refresh controller associated with this scroll view. Setting this property adds the refresh controller to the scroll view, enabling pull-to-refresh functionality. Set to nil to remove it. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_refresh_controller(const RefreshController& value) const; -#endif - /** * @brief Returns the `rulerViewClass` property of `NSScrollView`. * @return The converted Objective-C result. @@ -472,15 +416,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_rulers_visible(bool value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `scrollGestureForRelationships` property of `NSScrollView`. - * @details A gesture recognizer for setting up failure or exclusion relationships against scrolling gestures - * @return The converted Objective-C result. - */ - GestureRecognizer scroll_gesture_for_relationships() const; -#endif - /** * @brief Returns the `scrollerInsets` property of `NSScrollView`. * @details The distance the scrollers are inset from the edge of the scroll view. @@ -527,24 +462,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_scrolls_dynamically(bool value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `touchScrollingEnabled` property of `NSScrollView`. - * @details Enable touch scrolling Defaults to 'true'. - * @return The converted Objective-C result. - */ - bool is_touch_scrolling_enabled() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `touchScrollingEnabled` property of `NSScrollView`. - * @details Enable touch scrolling Defaults to 'true'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_touch_scrolling_enabled(bool value) const; -#endif - /** * @brief Returns the `usesPredominantAxisScrolling` property of `NSScrollView`. * @details Some content is scrollable in both the horizontal and vertical axes, but is predominantly scrolled one axis at a time. Other content (such as a drawing canvas) should scroll freely in both axes. Traditionally this is not an issue with scroll wheels since they can only scroll in one direction at a time. With scroll balls and touch surfaces, it becomes more difficult to determine the user's intention. This property helps NSScrollView determine the user's intention by specifying the type of scrolling content. When set to YES, NSScrollView will only scroll in the predominate direction the user is scrolling. The default value is YES for apps build on 10.7; NO otherwise. diff --git a/include/generated/secure_unarchive_from_data_transformer.h b/include/generated/secure_unarchive_from_data_transformer.h index 38175d0b..16f92c57 100644 --- a/include/generated/secure_unarchive_from_data_transformer.h +++ b/include/generated/secure_unarchive_from_data_transformer.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSSecureUnarchiveFromDataTransformer` (Foundation). - * @details A value transformer that converts data to and from classes that support secure coding. This class provides a default ''ValueTransformer'' implementation for secure decoding. This class attempts to decode data into the classes listed within ''allowedTopLevelClasses'', which includes ''NSArray'', ''NSDictionary'', ''NSSet'', ''NSString'', ''NSNumber'', ''NSDate'', ''NSData'', ''NSURL'', ''NSUUID'', and ''NSNull''. To archive or unarchive other classes that support ''NSSecureCoding'', create a subclass and override ''allowedTopLevelClasses'' to list the classes to transform. To use ''NSSecureUnarchiveFromDataTransformer'' with \, use the name of this class, or the name of a subclass you implement, as the name of the transformer for an entity's attribute within a Core Data Model. If you use your own transformer subclass, register it with your app before intializing your persistent container with Core Data. For an example of subclassing ''NSSecureUnarchiveFromDataTransformer'', see \, which has a 'ColorToDataTransformer' class that transforms \ to ''NSData'' and the reverse, to support archiving instances of \. + * @details A value transformer which transforms values to and from \\c NSData by archiving and unarchiving using secure coding. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ValueTransformer. * diff --git a/include/generated/segmented_control.h b/include/generated/segmented_control.h index 474068a4..1fc2bb22 100644 --- a/include/generated/segmented_control.h +++ b/include/generated/segmented_control.h @@ -33,10 +33,10 @@ namespace cocoon * cocoon::SegmentedControl segmented_control{}; * segmented_control.set_border_shape(cocoon::ControlBorderShape::Automatic); * auto border_shape = segmented_control.border_shape(); - * segmented_control.set_role(cocoon::SegmentedControlRole::Automatic); - * auto role = segmented_control.role(); * segmented_control.set_segment_count(1); * auto segment_count = segmented_control.segment_count(); + * segmented_control.set_segment_distribution(cocoon::SegmentDistribution::Fit); + * auto segment_distribution = segmented_control.segment_distribution(); * segmented_control.alignment_for_segment(1); * segmented_control.image_for_segment(1); * segmented_control.image_scaling_for_segment(1); @@ -237,22 +237,6 @@ namespace cocoon * @return The converted Objective-C result. */ std::int64_t index_of_selected_item() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `role` property of `NSSegmentedControl`. - * @return The converted Objective-C result. - */ - SegmentedControlRole role() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `role` property of `NSSegmentedControl`. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_role(SegmentedControlRole value) const; -#endif - /** * @brief Returns the `segmentCount` property of `NSSegmentedControl`. * @return The converted Objective-C result. diff --git a/include/generated/set_command.h b/include/generated/set_command.h index 612ad7bb..6c326bba 100644 --- a/include/generated/set_command.h +++ b/include/generated/set_command.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSSetCommand` (Foundation). - * @details A command that sets one or more attributes or relationships to one or more values. An instance of 'NSSetCommand' sets one or more attributes or relationships to one or more values; for example, it may set the (x, y) coordinates for a window's position or set the name of a document. 'NSSetCommand' is part of Cocoa's built-in scripting support. It works automatically to support the 'set' command through key-value coding. Most applications don't need to subclass 'NSSetCommand' or call its methods. 'NSSetCommand' uses available scripting class descriptions to determine whether it should set a value for an attribute (or property), or set a value for all elements (to-many objects). For the latter, it invokes \; for the former, it invokes \ (or, if the receiver overrides \, it invokes that method, to support backward binary compatibility.) For information on working with 'set' commands, see [Getting and Setting Properties and Elements](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_get_set/SAppsGetSet.html\#//apple_ref/doc/uid/TP40002164-CH18) in [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html\#//apple_ref/doc/uid/TP40002164). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptCommand. * @@ -43,13 +42,11 @@ namespace cocoon using ScriptCommand::set_receivers_specifier; /** * @brief Calls `-[NSSetCommand setReceiversSpecifier:]`. - * @details Splits off the inner-most child specifier from the receivers specifier. * @param receivers_ref Argument converted to the Objective-C parameter of the same role. */ void set_receivers_specifier(const ScriptObjectSpecifier& receivers_ref) const; /** * @brief Returns the `keySpecifier` property of `NSSetCommand`. - * @details The key specifier for the set operation. * @return The converted Objective-C result. */ ScriptObjectSpecifier key_specifier() const; diff --git a/include/generated/socket_port.h b/include/generated/socket_port.h index 781763cb..02003346 100644 --- a/include/generated/socket_port.h +++ b/include/generated/socket_port.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSSocketPort` (Foundation). - * @details A port that represents a BSD socket. A ''NSSocketPort'' object can be used as an endpoint for distributed object connections. Companion classes, ''NSMachPort'' and ''NSMessagePort'', allow for local (on the same machine) communication only. The ''NSSocketPort'' class allows for both local and remote communication, but may be more expensive than the others for the local case. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Port. * @@ -41,31 +40,26 @@ namespace cocoon explicit SocketPort(Adopt adopt); /** * @brief Returns the `address` property of `NSSocketPort`. - * @details The receiver's socket address structure stored inside an ''NSData'' object. * @return The converted Objective-C result. */ std::vector address() const; /** * @brief Returns the `protocol` property of `NSSocketPort`. - * @details The protocol that the receiver's socket uses. * @return The converted Objective-C result. */ int protocol() const; /** * @brief Returns the `protocolFamily` property of `NSSocketPort`. - * @details The protocol family of the receiver's socket. * @return The converted Objective-C result. */ int protocol_family() const; /** * @brief Returns the `socket` property of `NSSocketPort`. - * @details The receiver's native socket identifier on the platform. * @return The converted Objective-C result. */ int socket() const; /** * @brief Returns the `socketType` property of `NSSocketPort`. - * @details The type of the receiver's socket. * @return The converted Objective-C result. */ int socket_type() const; diff --git a/include/generated/socket_port_name_server.h b/include/generated/socket_port_name_server.h index cb897063..0473f69c 100644 --- a/include/generated/socket_port_name_server.h +++ b/include/generated/socket_port_name_server.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSSocketPortNameServer` (Foundation). - * @details \@DeprecationSummary { Use ''NSXPCConnection'' instead. } A port name server that takes and returns socket ports. Port removal functionality is supported by the ''removePortForName:'' method and should be used to remove invalid socket ports. Unlike the other port name servers, ''NSSocketPortNameServer'' can operate over a network. By registering your socket ports, you make them available to other computers on the local network without hard-coding the TCP port numbers. Clients just need to know the name of the port. ''NSPortNameServer'' is implemented using ''NetService'' and registers ports in the local network domain. The registered name of a port must be unique within the local domain, not just the local host. The name server only supports TCP/IP (either IPv4 or IPv6) sockets. > Note: > Prior to OS X 10.2, ''NSSocketPortNameServer'' was inoperable. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref PortNameServer. * @@ -50,14 +49,12 @@ namespace cocoon using PortNameServer::remove_port_for_name; /** * @brief Calls `-[NSSocketPortNameServer portForName:]`. - * @details Looks up and returns the port registered under the specified name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Port port_for_name(const std::string& name) const; /** * @brief Calls `-[NSSocketPortNameServer portForName:host:]`. - * @details Looks up and returns the port registered under the specified name on a given host. * @param name Argument converted to the Objective-C parameter of the same role. * @param host Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -65,7 +62,6 @@ namespace cocoon Port port_for_name(const std::string& name, const std::string& host) const; /** * @brief Calls `-[NSSocketPortNameServer portForName:host:nameServerPortNumber:]`. - * @details Looks up and returns the port registered under the specified name on a given host, using the specified port number for the name server. * @param name Argument converted to the Objective-C parameter of the same role. * @param host Argument converted to the Objective-C parameter of the same role. * @param port_number Argument converted to the Objective-C parameter of the same role. @@ -74,7 +70,6 @@ namespace cocoon Port port_for_name(const std::string& name, const std::string& host, std::uint16_t port_number) const; /** * @brief Calls `-[NSSocketPortNameServer registerPort:name:]`. - * @details Registers a given port as a network service with the specified name. * @param port Argument converted to the Objective-C parameter of the same role. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -82,7 +77,6 @@ namespace cocoon bool register_port(const Port& port, const std::string& name) const; /** * @brief Calls `-[NSSocketPortNameServer registerPort:name:nameServerPortNumber:]`. - * @details Registers a given port as a network service with the specified name and name server port number. * @param port Argument converted to the Objective-C parameter of the same role. * @param name Argument converted to the Objective-C parameter of the same role. * @param port_number Argument converted to the Objective-C parameter of the same role. @@ -91,26 +85,22 @@ namespace cocoon bool register_port(const Port& port, const std::string& name, std::uint16_t port_number) const; /** * @brief Calls `-[NSSocketPortNameServer removePortForName:]`. - * @details Unregisters the port for a given name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool remove_port_for_name(const std::string& name) const; /** * @brief Calls `+[NSSocketPortNameServer sharedInstance]`. - * @details Returns the shared instance of the socket port name server. * @return The converted Objective-C result. */ static Object shared_instance(); /** * @brief Returns the `defaultNameServerPortNumber` property of `NSSocketPortNameServer`. - * @details The default port number for the name server. * @return The converted Objective-C result. */ std::uint16_t default_name_server_port_number() const; /** * @brief Sets the `defaultNameServerPortNumber` property of `NSSocketPortNameServer`. - * @details The default port number for the name server. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_default_name_server_port_number(std::uint16_t value) const; diff --git a/include/generated/sort_descriptor.h b/include/generated/sort_descriptor.h index da342e72..6d734816 100644 --- a/include/generated/sort_descriptor.h +++ b/include/generated/sort_descriptor.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSSortDescriptor` (Foundation). - * @details An immutable description of how to order a collection of objects according to a property common to all the objects. You construct instances of ''NSSortDescriptor'' by specifying the key path of the property to compare and the order of the sort (ascending or descending). Optionally, you can also specify a selector to use to perform the comparison, which allows you to specify other comparison selectors, such as ''NSString/localizedStandardCompare(:)'' and ''NSString/localizedCaseInsensitiveCompare(:)''. Sorting raises an exception if the objects don't respond to the sort descriptor's comparison selector. You can use sort descriptors for the following: - Sorting an array (an instance of ''NSArray'' or ''NSMutableArray'' — see ''NSArray/sortedArray(using:)-82wi1'' and ''NSMutableArray/sort(using:)-4eh07'') - Comparing two objects directly (see ''compare(:to:)'') - Specifying the order of objects that return from a Core Data fetch request (see \) * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,12 +44,10 @@ namespace cocoon explicit SortDescriptor(Adopt adopt); /** * @brief Calls `-[NSSortDescriptor allowEvaluation]`. - * @details Forces a securely decoded sort descriptor to allow evaluation. When securely decoding 'NSSortDescriptor' objects encoded using 'NSSecureCoding', evaluation is disabled because it is potentially unsafe to evaluate descriptors you get out of an archive. Before you enable evaluation, you should validate key paths, selectors, and related properties to ensure no erroneous or malicious code will be executed. Once you've preflighted the sort descriptor, you can enable it for evaluation by calling this method. */ void allow_evaluation() const; /** * @brief Calls `-[NSSortDescriptor compareObject:toObject:]`. - * @details Returns a comparison result value that indicates the sort order of two objects. The ordering is determined by comparing the values specified by the sort descriptor's key of 'object1' and 'object2' using the selector specified by the sort descriptor's selector. - Parameters: - object1: The object to compare with 'object2'. This object must have a property accessible using the key-path specified by the sort descriptor's key. - object2: The object to compare with 'object1'. This object must have a property accessible using the key-path specified by the sort descriptor's key. - Returns: 'NSOrderedAscending' if 'object1' is less than 'object2', 'NSOrderedDescending' if 'object1' is greater than 'object2', or 'NSOrderedSame' if 'object1' is equal to 'object2'. * @param object1 Argument converted to the Objective-C parameter of the same role. * @param object2 Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -58,31 +55,26 @@ namespace cocoon ComparisonResult compare_object(const Object& object1, const Object& object2) const; /** * @brief Returns the `ascending` property of `NSSortDescriptor`. - * @details A Boolean value that indicates whether the receiver specifies sorting in ascending order. 'YES' if the receiver specifies sorting in ascending order, otherwise 'NO'. * @return The converted Objective-C result. */ bool ascending() const; /** * @brief Returns the `comparator` property of `NSSortDescriptor`. - * @details The comparator for the sort descriptor. Call this property only for sort descriptors initialized with 'initWithKey:ascending:comparator:'. * @return The converted Objective-C result. */ std::function comparator() const; /** * @brief Returns the `key` property of `NSSortDescriptor`. - * @details The key that specifies the property to compare during sorting. * @return The converted Objective-C result. */ std::string key() const; /** * @brief Returns the `reversedSortDescriptor` property of `NSSortDescriptor`. - * @details Returns a sort descriptor that reverses the sort order. * @return The converted Objective-C result. */ Object reversed_sort_descriptor() const; /** * @brief Returns the `selector` property of `NSSortDescriptor`. - * @details The selector for comparing objects. * @return The converted Objective-C result. */ std::string selector() const; diff --git a/include/generated/specifier_test.h b/include/generated/specifier_test.h index 8a86bb27..606ba03d 100644 --- a/include/generated/specifier_test.h +++ b/include/generated/specifier_test.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSSpecifierTest` (Foundation). - * @details A script whose test that compares an object specifier against a value using a comparison operator. The specifiers are evaluated normally before the comparison operator is evaluated. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptWhoseTest. * diff --git a/include/generated/spell_checker.h b/include/generated/spell_checker.h index d36c5e56..f73a3011 100644 --- a/include/generated/spell_checker.h +++ b/include/generated/spell_checker.h @@ -161,17 +161,6 @@ namespace cocoon * @return The converted Objective-C result. */ bool has_learned_word(const std::string& word) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSSpellChecker ignoreGrammarRange:inSentence:inSpellDocumentWithTag:]`. - * @details This method should be called to ignore a particular grammar issue. The sentence should be the portion of the text corresponding to the range of an NSTextCheckingResult of grammar type. The grammarRange should be the range within that sentence of an individual issue, taken from the NSGrammarRange entry of one of the grammarDetails of the same NSTextCheckingResult. - * @param grammar_range Argument converted to the Objective-C parameter of the same role. - * @param sentence Argument converted to the Objective-C parameter of the same role. - * @param tag Argument converted to the Objective-C parameter of the same role. - */ - void ignore_grammar_range(const Range& grammar_range, const std::string& sentence, std::int64_t tag) const; -#endif - /** * @brief Calls `-[NSSpellChecker ignoreWord:inSpellDocumentWithTag:]`. * @details This method should be called from the client's implementation of -ignoreSpelling: diff --git a/include/generated/spell_server.h b/include/generated/spell_server.h index 2d65463d..92f852c2 100644 --- a/include/generated/spell_server.h +++ b/include/generated/spell_server.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSSpellServer` (Foundation). - * @details A server that your app uses to provide a spell checker service to other apps running in the system. A service provider is an application that declares its availability in a standard way, so that any other applications that wish to use it can do so. If you build a spelling checker that makes use of the ''NSSpellServer'' class and list it as an available service, then users of any application that makes use of \ or includes a Services menu will see your spelling checker as one of the available dictionaries. + * @details The server just handles all the checking in and IAC and delegates the real work to its delegate. A single server can handle more than one language. Services is used to rendezvous applications with servers. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,7 +48,7 @@ namespace cocoon explicit SpellServer(Adopt adopt); /** * @brief Calls `-[NSSpellServer isWordInUserDictionaries:caseSensitive:]`. - * @details Indicates whether a given word is in the user's list of learned words, regardless of the language. + * @details Way to query user's private dictionary(ies). * @param word Argument converted to the Objective-C parameter of the same role. * @param flag Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -56,7 +56,7 @@ namespace cocoon bool is_word_in_user_dictionaries(const std::string& word, bool flag) const; /** * @brief Calls `-[NSSpellServer registerLanguage:byVendor:]`. - * @details Registers the given language for the receiver with the given vendor name. + * @details Used to check in * @param language Argument converted to the Objective-C parameter of the same role. * @param vendor Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -64,7 +64,7 @@ namespace cocoon bool register_language(const std::string& language, const std::string& vendor) const; /** * @brief Calls `-[NSSpellServer run]`. - * @details Causes the receiver to start listening for spell-checking requests. + * @details Waits for spell-check request to come in. */ void run() const; /// @brief Signal for the delegate/data-source method behind `find_misspelled_word_in_string_language_word_count_count_only`; connect a callback with `find_misspelled_word_in_string_language_word_count_count_only().connect(...)`. diff --git a/include/generated/status_item.h b/include/generated/status_item.h index 996bffad..6ff94295 100644 --- a/include/generated/status_item.h +++ b/include/generated/status_item.h @@ -11,8 +11,6 @@ namespace cocoon class Menu; class StatusBar; class StatusBarButton; - class StatusItemExpandedInterfaceSession; - class View; /** * @brief C++ handle for the Objective-C class `NSStatusItem` (AppKit). @@ -23,22 +21,19 @@ namespace cocoon * #include * * cocoon::StatusItem status_item; - * status_item.set_action("text"); - * status_item.did_begin_expanded_interface_session().connect([](auto&&...) {}); + * status_item.set_autosave_name("text"); * @endcode * * @par Common tasks * Snippets built from this class's own members (values are placeholders). * @code * cocoon::StatusItem status_item{}; - * status_item.set_action("text"); - * auto action = status_item.action(); * status_item.set_autosave_name("text"); * auto autosave_name = status_item.autosave_name(); * status_item.set_behavior(cocoon::StatusItemBehavior::RemovalAllowed); * auto behavior = status_item.behavior(); - * status_item.did_begin_expanded_interface_session().connect([](cocoon::StatusItemExpandedInterfaceSession a0) {}); - * status_item.did_end_expanded_interface_session_animated().connect([](bool a0) {}); + * status_item.set_length(1); + * auto length = status_item.length(); * @endcode * @see https://developer.apple.com/documentation/appkit/nsstatusitem */ @@ -51,16 +46,6 @@ namespace cocoon StatusItem(std::nullptr_t); /// @brief Wraps an existing retained native object without creating a new one. explicit StatusItem(Adopt adopt); - /** - * @brief Returns the `action` property of `NSStatusItem`. - * @return The converted Objective-C result. - */ - std::string action() const; - /** - * @brief Sets the `action` property of `NSStatusItem`. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_action(const std::string& value) const; /** * @brief Returns the `autosaveName` property of `NSStatusItem`. * @details Specifies a unique name for persisting visibility information. If none is specified, one is automatically chosen. Apps with multiple status bar items should set an autosave after creation. Setting to nil resets the automatically chosen name and clears saved information. @@ -91,15 +76,6 @@ namespace cocoon * @return The converted Objective-C result. */ StatusBarButton button() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `expandedInterfaceSession` property of `NSStatusItem`. - * @details A session object tracking the lifecycle of a currently showing expanded interface, if any. Will be set to a valid session object before invocation of -statusItem:didBeginExpandedInterfaceSession:, and cleared to nil before invocation of -statusItemDidEndExpandedInterfaceSession:animated: on the expandedInterfaceDelegate. - * @return The converted Objective-C result. - */ - StatusItemExpandedInterfaceSession expanded_interface_session() const; -#endif - /** * @brief Returns the `length` property of `NSStatusItem`. * @details The amount of space in the status bar that should be allocated to the receiver. \\c NSVariableStatusItemLength will adjust the length to the size of the status item's contents and \\c NSSquareStatusItemLength will keep the length the same as the status bar's height. @@ -130,30 +106,6 @@ namespace cocoon * @return The converted Objective-C result. */ StatusBar status_bar() const; - /** - * @brief Returns the `target` property of `NSStatusItem`. - * @details An optional target/action to be invoked when using a custom view rather than -button. Status items with no -expandedInterfaceDelegate and which use -view will receive this when interacted with. - * @return The converted Objective-C result. - */ - Object target() const; - /** - * @brief Sets the `target` property of `NSStatusItem`. - * @details An optional target/action to be invoked when using a custom view rather than -button. Status items with no -expandedInterfaceDelegate and which use -view will receive this when interacted with. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_target(const Object& value) const; - /** - * @brief Returns the `view` property of `NSStatusItem`. - * @details An optional view to display in the status bar instead of -button. -button is preferred in most cases as it can alter its appearance automatically. - * @return The converted Objective-C result. - */ - View view() const; - /** - * @brief Sets the `view` property of `NSStatusItem`. - * @details An optional view to display in the status bar instead of -button. -button is preferred in most cases as it can alter its appearance automatically. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_view(const View& value) const; /** * @brief Returns the `visible` property of `NSStatusItem`. * @details Specifies if the status item is currently visible in the status bar, even if it is obscured by the application menu. Defaults to YES. Persisted based on the -autosaveName. This is observable through KVO. @@ -166,25 +118,5 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_visible(bool value) const; -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `did_begin_expanded_interface_session`; connect a callback with `did_begin_expanded_interface_session().connect(...)`. - Signal did_begin_expanded_interface_session() const - { - return Signal(handle(), "did_begin_expanded_interface_session"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `did_end_expanded_interface_session_animated`; connect a callback with `did_end_expanded_interface_session_animated().connect(...)`. - Signal did_end_expanded_interface_session_animated() const - { - return Signal(handle(), "did_end_expanded_interface_session_animated"); - } -#endif - - protected: -#ifdef COCOON_MACOS_27 - static void install_expanded_interface_delegate_delegate_(void* native); -#endif }; } diff --git a/include/generated/status_item_expanded_interface_session.h b/include/generated/status_item_expanded_interface_session.h deleted file mode 100644 index 86ffe8b3..00000000 --- a/include/generated/status_item_expanded_interface_session.h +++ /dev/null @@ -1,51 +0,0 @@ -#pragma once - -#include "generated/availability.h" - -#ifdef COCOON_MACOS_27 -#include "generated/enums.h" -#include "generated/structs.h" -#include "object.h" -#include "types.h" - -namespace cocoon -{ - /** - * @brief C++ handle for the Objective-C class `NSStatusItemExpandedInterfaceSession` (AppKit). - * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. - * - * @par Example - * @code - * #include - * - * cocoon::StatusItemExpandedInterfaceSession status_item_expanded_interface_session; - * @endcode - * - * @par Common tasks - * Snippets built from this class's own members (values are placeholders). - * @code - * cocoon::StatusItemExpandedInterfaceSession status_item_expanded_interface_session{}; - * status_item_expanded_interface_session.cancel(); - * @endcode - * @see https://developer.apple.com/documentation/appkit/nsstatusitemexpandedinterfacesession - */ - class StatusItemExpandedInterfaceSession : public Object - { - public: - /// @brief Creates a new `NSStatusItemExpandedInterfaceSession` instance and returns a handle to it. - explicit StatusItemExpandedInterfaceSession(); - /// @brief Creates a null handle that refers to no native object. - StatusItemExpandedInterfaceSession(std::nullptr_t); - /// @brief Wraps an existing retained native object without creating a new one. - explicit StatusItemExpandedInterfaceSession(Adopt adopt); -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSStatusItemExpandedInterfaceSession cancel]`. - * @details Cancels tracking of the expanded interface state in the menu bar system. NSStatusItemExpandedInterfaceDelegate will receive -statusItemDidEndExpandedInterfaceSession:animated: after cancellation. - */ - void cancel() const; -#endif - }; -} - -#endif diff --git a/include/generated/stream.h b/include/generated/stream.h index 1da9a8c0..a2911806 100644 --- a/include/generated/stream.h +++ b/include/generated/stream.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSStream` (Foundation). - * @details An abstract class representing a stream. This class's interface is common to all Cocoa stream classes, including its concrete subclasses ''InputStream'' and ''OutputStream''. ''Stream'' objects provide an easy way to read and write data to and from a variety of media in a device-independent way. You can create stream objects for data located in memory, in a file, or on a network (using sockets), and you can use stream objects without loading all of the data into memory at once. By default, ''Stream'' instances that aren't file-based are non-seekable, one-way streams (although custom seekable subclasses are possible). After you provide or consume data, you can't retrieve the data from the stream. \#\#\# Subclassing Notes ''Stream'' is an abstract class, incapable of instantiation and intended for you to subclass it. It publishes a programmatic interface that all subclasses must adopt and provide implementations for. The two Apple-provided concrete subclasses of ''Stream'', ''InputStream'' and ''OutputStream'', are suitable for most purposes. However, there might be situations when you want a peer subclass to ''InputStream'' and ''OutputStream''. For example, you might want a class that implements a full-duplex (two-way) stream, or a class whose instances are capable of seeking through a stream. \#\#\#\# Methods to Override All subclasses must fully implement the following methods: - ''open()'' and ''close()'' Implement ''open()'' to open the stream for reading or writing and make the stream available to the client directly or, if the stream object is scheduled on a run loop, to the delegate. Implement ''close()'' to close the stream and remove the stream object from the run loop, if necessary. A closed stream should still be able to accept new properties and report its current properties. Once you close a stream, you can't reopen it. - ''delegate'' Return and set the delegate. By a default, a stream object must be its own delegate; so a ''delegate'' message with an argument of 'nil' should restore this delegate. Don't retain the delegate to prevent retain cycles. To learn about delegates and delegation, read "Delegation" in Cocoa Fundamentals Guide. - ''schedule(in:forMode:)'' and ''remove(from:forMode:)'' Implement ''schedule(in:forMode:)'' to schedule the stream object on the specified run loop for the specified mode. Implement ''remove(from:forMode:)'' to remove the object from the run loop. See the documentation of the ''RunLoop'' class for details. Once the stream object for an open stream is scheduled on a run loop, it is the responsibility of the subclass as it processes stream data to send ''StreamDelegate/stream(:handle:)'' messages to its delegate. - ''property(forKey:)'' and ''setProperty(:forKey:)'' Implement these methods to return and set, respectively, the property value for the specified key. You may add custom properties, but be sure to handle all properties defined by ''Stream'' as well. - ''streamStatus'' and ''streamError'' Implement ''streamStatus'' to return the current status of the stream as a ''Status'' constant; you may define new ''Status'' constants, but be sure to handle the system defined constants properly. Implement ''streamError'' to return an ''NSError'' object representing the current error. You might decide to return a custom ''NSError'' object that can provide complete and localized information about the error. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,12 +47,10 @@ namespace cocoon explicit Stream(Adopt adopt); /** * @brief Calls `-[NSStream close]`. - * @details Closes the receiver. Closing the stream terminates the flow of bytes and releases system resources that were reserved for the stream when it was opened. If the stream has been scheduled on a run loop, closing the stream implicitly removes the stream from the run loop. A stream that is closed can still be queried for its properties. */ void close() const; /** * @brief Calls `+[NSStream getBoundStreamsWithBufferSize:inputStream:outputStream:]`. - * @details Creates and returns by reference a bound pair of input and output streams. The created streams are bound to one another, such that any data written to 'outputStream' is received by 'inputStream'. - Parameters: - bufferSize: The size of the buffer, in bytes, used to transfer data from 'inputStream' to 'outputStream'. - inputStream: On return, contains an input stream. - outputStream: On return, contains an output stream. * @param buffer_size Argument converted to the Objective-C parameter of the same role. * @param input_stream Argument converted to the Objective-C parameter of the same role. * @param output_stream Argument converted to the Objective-C parameter of the same role. @@ -61,7 +58,6 @@ namespace cocoon static void get_bound_streams_with_buffer_size(std::uint64_t buffer_size, InputStream& input_stream, OutputStream& output_stream); /** * @brief Calls `+[NSStream getStreamsToHostWithName:port:inputStream:outputStream:]`. - * @details Creates and returns by reference an 'NSInputStream' object and 'NSOutputStream' object for a socket connection with a given host on a given port. - Parameters: - hostname: The host to which to connect. - port: The port to connect to on 'host'. - inputStream: Upon return, contains the input stream. If 'nil' is passed, the stream object is not created. - outputStream: Upon return, contains the output stream. If 'nil' is passed, the stream object is not created. * @param hostname Argument converted to the Objective-C parameter of the same role. * @param port Argument converted to the Objective-C parameter of the same role. * @param input_stream Argument converted to the Objective-C parameter of the same role. @@ -70,33 +66,28 @@ namespace cocoon static void get_streams_to_host_with_name(const std::string& hostname, std::int64_t port, InputStream& input_stream, OutputStream& output_stream); /** * @brief Calls `-[NSStream open]`. - * @details Opens the receiving stream. A stream must be created before it can be opened. Once opened, a stream cannot be closed and reopened. */ void open() const; /** * @brief Calls `-[NSStream propertyForKey:]`. - * @details Returns the receiver's property for a given key. - Parameter key: The key for one of the receiver's properties. - Returns: The receiver's property for the key 'key'. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object property_for_key(const std::string& key) const; /** * @brief Calls `-[NSStream removeFromRunLoop:forMode:]`. - * @details Removes the receiver from a given run loop running in a given mode. - Parameters: - aRunLoop: The run loop on which the receiver was scheduled. - mode: The mode for the run loop. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void remove_from_run_loop(const RunLoop& a_run_loop, const std::string& mode) const; /** * @brief Calls `-[NSStream scheduleInRunLoop:forMode:]`. - * @details Schedules the receiver on a given run loop in a given mode. Unless the client is polling the stream, it is responsible for ensuring that the stream is scheduled on at least one run loop and that at least one of the run loops on which the stream is scheduled is being run. - Parameters: - aRunLoop: The run loop on which to schedule the receiver. - mode: The mode for the run loop. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void schedule_in_run_loop(const RunLoop& a_run_loop, const std::string& mode) const; /** * @brief Calls `-[NSStream setProperty:forKey:]`. - * @details Attempts to set the value of a given property of the receiver and returns a Boolean value that indicates whether the value is accepted by the receiver. - Parameters: - property: The value for 'key'. - key: The key for one of the receiver's properties. - Returns: 'YES' if the value is accepted by the receiver, otherwise 'NO'. * @param property Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -104,13 +95,11 @@ namespace cocoon bool set_property(const Object& property, const std::string& key) const; /** * @brief Returns the `streamError` property of `NSStream`. - * @details An 'NSError' object representing the stream error, or 'nil' if no error has been encountered. * @return The converted Objective-C result. */ Error stream_error() const; /** * @brief Returns the `streamStatus` property of `NSStream`. - * @details The receiver's status. * @return The converted Objective-C result. */ StreamStatus stream_status() const; diff --git a/include/generated/task.h b/include/generated/task.h index 0cf4c742..76db9ada 100644 --- a/include/generated/task.h +++ b/include/generated/task.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTask` (Foundation). - * @details An object that represents a subprocess of the current process. Using this class, your program can run another program as a subprocess and monitor that program's execution. Unlike ''Thread'', it doesn't share memory space with the process that creates it. A process operates within an environment defined by the current values for several items: the current directory, standard input, standard output, standard error, and the values of any environment variables, inheriting its environment from the process that launches it. If there are any environment variables that should be different for the subprocess (for example, if the current directory needs to change), change it in the instance after initialization, before your app launches it. Your app can't change a process's environment while it's running. You can only run the subprocess once per instance. Subsequent attempts raise an error. > Important: > In a sandboxed app, child processes you create with this class inherit the sandbox of the parent app. Instead, write helper apps as XPC Services because it allows you to specify different sandbox entitlements for helper apps. For more information, see [Daemons and Services Programming Guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/Introduction.html\#//apple_ref/doc/uid/10000172i) and \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -51,23 +50,19 @@ namespace cocoon explicit Task(Adopt adopt); /** * @brief Calls `-[NSTask interrupt]`. - * @details Sends an interrupt signal to the receiver and all of its subtasks. If the task terminates as a result, which is the default behavior, an 'NSTaskDidTerminateNotification' gets sent to the default notification center. This method has no effect if the receiver was already launched and has already finished executing. If the system hasn't launched the receiver, this method raises an 'NSInvalidArgumentException'. It isn't always possible to interrupt the receiver because it might be ignoring the interrupt signal. This method sends 'SIGINT'. */ void interrupt() const; /** * @brief Calls `-[NSTask launch]`. - * @details Launches the task represented by the receiver. \@DeprecationSummary { Use ''run()'' instead. } Raises an 'NSInvalidArgumentException' if the launch path has not been set or is invalid or if it fails to create a process. */ void launch() const; /** * @brief Calls `-[NSTask launchAndReturnError:]`. - * @details Runs the process with the current environment. * @return The converted Objective-C result. */ bool launch_and_return_error() const; /** * @brief Calls `+[NSTask launchedTaskWithExecutableURL:arguments:error:terminationHandler:]`. - * @details Creates and runs a task with a specified executable and arguments. - Parameter url: The URL for the executable. - Parameter arguments: An array of 'NSString' objects that supplies the arguments to the task. - Parameter error: If an error occurs, upon return contains an 'NSError' object that describes the problem. - Parameter terminationHandler: The system invokes this completion block when the task has completed. - Returns: An initialized 'NSTask' object with the environment of the current process. * @param url Argument converted to the Objective-C parameter of the same role. * @param arguments Argument converted to the Objective-C parameter of the same role. * @param termination_handler Argument converted to the Objective-C parameter of the same role. @@ -76,7 +71,6 @@ namespace cocoon static Task launched_task_with_executable_url(const URL& url, const std::vector& arguments, std::function termination_handler); /** * @brief Calls `+[NSTask launchedTaskWithLaunchPath:arguments:]`. - * @details Creates and launches a task with a specified executable and arguments. \@deprecated Use 'launchedTaskWithExecutableURL:arguments:error:terminationHandler:' instead. The task inherits its environment from the process that invokes this method. The 'NSTask' object converts both 'path' and the strings in 'arguments' to appropriate C-style strings (using 'fileSystemRepresentation') before passing them to the task via 'argv[]'. The strings in 'arguments' don't undergo shell expansion, so you don't need to do special quoting, and shell variables, such as '$PWD', aren't resolved. - Parameter path: The path to the executable. - Parameter arguments: An array of 'NSString' objects that supplies the arguments to the task. - Returns: An initialized 'NSTask' object with the supplied 'arguments'. * @param path Argument converted to the Objective-C parameter of the same role. * @param arguments Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -84,191 +78,161 @@ namespace cocoon static Task launched_task_with_launch_path(const std::string& path, const std::vector& arguments); /** * @brief Calls `-[NSTask resume]`. - * @details Resumes execution of a suspended task. If the system sent multiple 'suspend' messages to the receiver, an equal number of 'resume' messages must be sent before the task resumes execution. - Returns: 'YES' if the receiver was able to resume execution, 'NO' otherwise. * @return The converted Objective-C result. */ bool resume() const; /** * @brief Calls `-[NSTask suspend]`. - * @details Suspends execution of the receiver task. Multiple 'suspend' messages can be sent, but they must be balanced with an equal number of 'resume' messages before the task resumes execution. - Returns: 'YES' if the receiver was successfully suspended, 'NO' otherwise. * @return The converted Objective-C result. */ bool suspend() const; /** * @brief Calls `-[NSTask terminate]`. - * @details Sends a terminate signal to the receiver and all of its subtasks. If the task terminates as a result, which is the default behavior, an 'NSTaskDidTerminateNotification' gets sent to the default notification center. This method has no effect if the receiver was already launched and has already finished executing. If the receiver hasn't been launched yet, this method raises an 'NSInvalidArgumentException'. It's not always possible to terminate the receiver because it might be ignoring the terminate signal. This method sends 'SIGTERM'. */ void terminate() const; /** * @brief Calls `-[NSTask waitUntilExit]`. - * @details Blocks the process until the receiver is finished. This method first checks to see if the receiver is still running using 'isRunning'. Then it polls the current run loop using 'NSDefaultRunLoopMode' until the task completes. \@TabNavigator { \@Tab("Swift") { '''swift let task: NSTask = // Create and initialize a task task.launch() task.waitUntilExit() let status = task.terminationStatus if status == 0 { print("Task succeeded.") } else { print("Task failed.") } ''' } \@Tab("Objective-C") { '''objc NSTask task = // Create and initialize a task [task launch]; [task waitUntilExit]; int status = [task terminationStatus]; if (status == 0) { NSLog(\@"Task succeeded."); } else { NSLog(\@"Task failed."); } ''' } } 'waitUntilExit' does not guarantee that the 'terminationHandler' block has been fully executed before 'waitUntilExit' returns. */ void wait_until_exit() const; /** * @brief Returns the `arguments` property of `NSTask`. - * @details The command arguments that the system uses to launch the executable. The 'NSTask' object converts both 'path' and the strings in 'arguments' to appropriate C-style strings (using 'fileSystemRepresentation') before passing them to the task through 'argv[]'. The strings in 'arguments' don't undergo shell expansion, so you don't need to do special quoting, and shell variables, such as '$PWD', aren't resolved. * @return The converted Objective-C result. */ std::vector arguments() const; /** * @brief Sets the `arguments` property of `NSTask`. - * @details The command arguments that the system uses to launch the executable. The 'NSTask' object converts both 'path' and the strings in 'arguments' to appropriate C-style strings (using 'fileSystemRepresentation') before passing them to the task through 'argv[]'. The strings in 'arguments' don't undergo shell expansion, so you don't need to do special quoting, and shell variables, such as '$PWD', aren't resolved. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_arguments(const std::vector& value) const; /** * @brief Returns the `currentDirectoryPath` property of `NSTask`. - * @details Sets the current directory for the receiver. \@deprecated Use 'currentDirectoryURL' instead. If this method isn't used, the current directory is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the receiver has already been launched. * @return The converted Objective-C result. */ std::string current_directory_path() const; /** * @brief Sets the `currentDirectoryPath` property of `NSTask`. - * @details Sets the current directory for the receiver. \@deprecated Use 'currentDirectoryURL' instead. If this method isn't used, the current directory is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the receiver has already been launched. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_current_directory_path(const std::string& value) const; /** * @brief Returns the `currentDirectoryURL` property of `NSTask`. - * @details The current directory for the receiver. * @return The converted Objective-C result. */ URL current_directory_url() const; /** * @brief Sets the `currentDirectoryURL` property of `NSTask`. - * @details The current directory for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_current_directory_url(const URL& value) const; /** * @brief Returns the `environment` property of `NSTask`. - * @details The environment for the receiver. If this method isn't used, the environment is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @return The converted Objective-C result. */ std::map environment() const; /** * @brief Sets the `environment` property of `NSTask`. - * @details The environment for the receiver. If this method isn't used, the environment is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_environment(const std::map& value) const; /** * @brief Returns the `executableURL` property of `NSTask`. - * @details The receiver's executable. * @return The converted Objective-C result. */ URL executable_url() const; /** * @brief Sets the `executableURL` property of `NSTask`. - * @details The receiver's executable. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_executable_url(const URL& value) const; /** * @brief Returns the `launchPath` property of `NSTask`. - * @details Sets the receiver's executable. \@deprecated Use 'executableURL' instead. * @return The converted Objective-C result. */ std::string launch_path() const; /** * @brief Sets the `launchPath` property of `NSTask`. - * @details Sets the receiver's executable. \@deprecated Use 'executableURL' instead. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_launch_path(const std::string& value) const; /** * @brief Returns the `launchRequirementData` property of `NSTask`. - * @details The launch requirement data for the receiver. * @return The converted Objective-C result. */ std::vector launch_requirement_data() const; /** * @brief Sets the `launchRequirementData` property of `NSTask`. - * @details The launch requirement data for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_launch_requirement_data(const std::vector& value) const; /** * @brief Returns the `processIdentifier` property of `NSTask`. - * @details The receiver's process identifier. * @return The converted Objective-C result. */ int process_identifier() const; /** * @brief Returns the `qualityOfService` property of `NSTask`. - * @details The default quality of service level the system applies to operations the task executes. * @return The converted Objective-C result. */ QualityOfService quality_of_service() const; /** * @brief Sets the `qualityOfService` property of `NSTask`. - * @details The default quality of service level the system applies to operations the task executes. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_quality_of_service(QualityOfService value) const; /** * @brief Returns the `running` property of `NSTask`. - * @details A status that indicates whether the receiver is still running. * @return The converted Objective-C result. */ bool is_running() const; /** * @brief Returns the `standardError` property of `NSTask`. - * @details The standard error for the receiver. If this is an 'NSPipe' object, launching the receiver automatically closes the write end of the pipe in the current task. Don't create a handle for the pipe and pass that as the argument, or the system won't automatically close the write end of the pipe. If this method isn't used, the standard error is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @return The converted Objective-C result. */ Object standard_error() const; /** * @brief Sets the `standardError` property of `NSTask`. - * @details The standard error for the receiver. If this is an 'NSPipe' object, launching the receiver automatically closes the write end of the pipe in the current task. Don't create a handle for the pipe and pass that as the argument, or the system won't automatically close the write end of the pipe. If this method isn't used, the standard error is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standard_error(const Object& value) const; /** * @brief Returns the `standardInput` property of `NSTask`. - * @details The standard input for the receiver. If this is an 'NSPipe' object, launching the receiver automatically closes the read end of the pipe in the current task. Don't create a handle for the pipe and pass that as the argument, or the read end of the pipe won't be closed automatically. If this method isn't used, the standard input is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @return The converted Objective-C result. */ Object standard_input() const; /** * @brief Sets the `standardInput` property of `NSTask`. - * @details The standard input for the receiver. If this is an 'NSPipe' object, launching the receiver automatically closes the read end of the pipe in the current task. Don't create a handle for the pipe and pass that as the argument, or the read end of the pipe won't be closed automatically. If this method isn't used, the standard input is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standard_input(const Object& value) const; /** * @brief Returns the `standardOutput` property of `NSTask`. - * @details The standard output for the receiver. If this is an 'NSPipe' object, launching the receiver automatically closes the write end of the pipe in the current task. Don't create a handle for the pipe and pass that as the argument, or the write end of the pipe won't be closed automatically. If this method isn't used, the standard output is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @return The converted Objective-C result. */ Object standard_output() const; /** * @brief Sets the `standardOutput` property of `NSTask`. - * @details The standard output for the receiver. If this is an 'NSPipe' object, launching the receiver automatically closes the write end of the pipe in the current task. Don't create a handle for the pipe and pass that as the argument, or the write end of the pipe won't be closed automatically. If this method isn't used, the standard output is inherited from the process that created the receiver. This method raises an 'NSInvalidArgumentException' if the system has launched the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standard_output(const Object& value) const; /** * @brief Returns the `terminationHandler` property of `NSTask`. - * @details A completion block the system invokes when the task completes. The system passes the task object to the block to allow access to the task parameters, for example to determine if the task completed successfully. This block isn't guaranteed to be fully executed prior to 'waitUntilExit' returning. Setting the block to nil is valid, and stops the previous block from being invoked, as long as it hasn't started in any way. Only one termination handler block can be set at any time. If a terminationHandler is set on an NSTask, the NSTaskDidTerminateNotification notification is not posted for that task. + * @details A block to be invoked when the process underlying the NSTask terminates. Setting the block to nil is valid, and stops the previous block from being invoked, as long as it hasn't started in any way. The NSTask is passed as the argument to the block so the block does not have to capture, and thus retain, it. The block is copied when set. Only one termination handler block can be set at any time. The execution context in which the block is invoked is undefined. If the NSTask has already finished, the block is executed immediately/soon (not necessarily on the current thread). If a terminationHandler is set on an NSTask, the NSTaskDidTerminateNotification notification is not posted for that task. Also note that -waitUntilExit won't wait until the terminationHandler has been fully executed. You cannot use this property in a concrete subclass of NSTask which hasn't been updated to include an implementation of the storage and use of it. * @return The converted Objective-C result. */ std::function termination_handler() const; /** * @brief Sets the `terminationHandler` property of `NSTask`. - * @details A completion block the system invokes when the task completes. The system passes the task object to the block to allow access to the task parameters, for example to determine if the task completed successfully. This block isn't guaranteed to be fully executed prior to 'waitUntilExit' returning. Setting the block to nil is valid, and stops the previous block from being invoked, as long as it hasn't started in any way. Only one termination handler block can be set at any time. If a terminationHandler is set on an NSTask, the NSTaskDidTerminateNotification notification is not posted for that task. + * @details A block to be invoked when the process underlying the NSTask terminates. Setting the block to nil is valid, and stops the previous block from being invoked, as long as it hasn't started in any way. The NSTask is passed as the argument to the block so the block does not have to capture, and thus retain, it. The block is copied when set. Only one termination handler block can be set at any time. The execution context in which the block is invoked is undefined. If the NSTask has already finished, the block is executed immediately/soon (not necessarily on the current thread). If a terminationHandler is set on an NSTask, the NSTaskDidTerminateNotification notification is not posted for that task. Also note that -waitUntilExit won't wait until the terminationHandler has been fully executed. You cannot use this property in a concrete subclass of NSTask which hasn't been updated to include an implementation of the storage and use of it. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_termination_handler(std::function value) const; /** * @brief Returns the `terminationReason` property of `NSTask`. - * @details The reason the system terminated the task. The possible values are described in 'NSTaskTerminationReason'. * @return The converted Objective-C result. */ TaskTerminationReason termination_reason() const; /** * @brief Returns the `terminationStatus` property of `NSTask`. - * @details The exit status the receiver's executable returns. Each task defines and documents how your app should interpret the return value. For example, many commands return 0 if they complete successfully or an error code if they don't. You'll need to look at the documentation for that task to learn what values it returns under what circumstances. This method raises an 'NSInvalidArgumentException' if the receiver is still running. Verify that the receiver isn't running before you use it. * @return The converted Objective-C result. */ int termination_status() const; diff --git a/include/generated/text_attachment_view_provider.h b/include/generated/text_attachment_view_provider.h index ff007604..d3429514 100644 --- a/include/generated/text_attachment_view_provider.h +++ b/include/generated/text_attachment_view_provider.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextAttachmentViewProvider` (AppKit). - * @details A container object that associates a text attachment at a particular document location with a view object. Use 'NSTextAttachmentViewProvider' when you need to represent document locations in terms of an ''NSTextLocation'' or an ''NSTextRange'' or you want to support view-based text attachments. The view provider controls the view placement and layout without requiring view classes to be aware of the text attachment coordination using a ''NSTextLayoutManager'' in macOS 12 or iOS 15 and later. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -50,7 +49,6 @@ namespace cocoon explicit TextAttachmentViewProvider(Adopt adopt); /** * @brief Calls `-[NSTextAttachmentViewProvider attachmentBoundsForAttributes:location:textContainer:proposedLineFragment:position:]`. - * @details Returns the layout bounds for an attachment at a specific text location that contains the text attributes you specify. - Parameters: - attributes: A dictionary that contains a list of key and attribute pairs that describe the customization of the string. - location: An ''NSTextLocation'' that indicates the location of the attachment inside the document. - textContainer: The ''NSTextContainer'' that defines the area to fill in with text. - proposedLineFragment: A \ that describes the boundaries of the line fragment. - position: A \ inside 'proposedLineFragment'. - Returns: A \ that describes the bounds of the attachment. * @param attributes Argument converted to the Objective-C parameter of the same role. * @param location Argument converted to the Objective-C parameter of the same role. * @param text_container Argument converted to the Objective-C parameter of the same role. @@ -61,42 +59,35 @@ namespace cocoon Rect attachment_bounds_for_attributes(const std::map& attributes, const Object& location, const TextContainer& text_container, const Rect& proposed_line_fragment, const Point& position) const; /** * @brief Calls `-[NSTextAttachmentViewProvider loadView]`. - * @details Creates the custom view hierarchy for this attachment. Use this method to create a custom view hierarchy. Don't call this method directly; the framework calls it at the appropriate time. */ void load_view() const; /** * @brief Returns the `textAttachment` property of `NSTextAttachmentViewProvider`. - * @details The text attachment for this view. Specify the value of this property at initialization time using the ''NSTextAttachmentViewProvider/init(textAttachment:parentView:textLayoutManager:location:)'' initializer. * @return The converted Objective-C result. */ TextAttachment text_attachment() const; /** * @brief Returns the `textLayoutManager` property of `NSTextAttachmentViewProvider`. - * @details The text layout manager for this view. Specify the value of this property at initialization time using the ''NSTextAttachmentViewProvider/init(textAttachment:parentView:textLayoutManager:location:)'' initializer. * @return The converted Objective-C result. */ TextLayoutManager text_layout_manager() const; /** * @brief Returns the `tracksTextAttachmentViewBounds` property of `NSTextAttachmentViewProvider`. - * @details A Boolean value that determines the text attachment's bounds policy. If 'true', the framework calls the 'textAttachment' property's ''NSTextAttachmentViewProvider/attachmentBounds(for:location:textContainer:proposedLineFragment:position:)'' method and examines the text attachment view provider to determine the bounds instead of using the 'bounds' property of this instance. Defaults to 'false'. * @return The converted Objective-C result. */ bool tracks_text_attachment_view_bounds() const; /** * @brief Sets the `tracksTextAttachmentViewBounds` property of `NSTextAttachmentViewProvider`. - * @details A Boolean value that determines the text attachment's bounds policy. If 'true', the framework calls the 'textAttachment' property's ''NSTextAttachmentViewProvider/attachmentBounds(for:location:textContainer:proposedLineFragment:position:)'' method and examines the text attachment view provider to determine the bounds instead of using the 'bounds' property of this instance. Defaults to 'false'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tracks_text_attachment_view_bounds(bool value) const; /** * @brief Returns the `view` property of `NSTextAttachmentViewProvider`. - * @details The text attachment's view. The getter first invokes ''loadView'' if the view hasn't been set yet. > Important: Subclasses must call the superclass implementation if they override the setter or getter. * @return The converted Objective-C result. */ View view() const; /** * @brief Sets the `view` property of `NSTextAttachmentViewProvider`. - * @details The text attachment's view. The getter first invokes ''loadView'' if the view hasn't been set yet. > Important: Subclasses must call the superclass implementation if they override the setter or getter. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_view(const View& value) const; diff --git a/include/generated/text_block.h b/include/generated/text_block.h index 291be628..f1b4c407 100644 --- a/include/generated/text_block.h +++ b/include/generated/text_block.h @@ -15,6 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextBlock` (AppKit). + * @details NSTextBlock is the basic object for text block layout, and the superclass of the other classes. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -31,11 +32,11 @@ namespace cocoon * cocoon::TextBlock text_block{}; * text_block.set_background_color(cocoon::Color()); * auto background_color = text_block.background_color(); - * text_block.set_vertical_alignment(cocoon::TextBlockVerticalAlignment::Top); + * text_block.set_vertical_alignment(cocoon::TextBlockVerticalAlignment::TopAlignment); * auto vertical_alignment = text_block.vertical_alignment(); * text_block.border_color_for_edge(cocoon::RectEdge::MinX); - * text_block.border_color_for_rect_edge(cocoon::CGRectEdge::MinXEdge); * text_block.set_border_color(cocoon::Color()); + * text_block.set_border_color(cocoon::Color(), cocoon::RectEdge::MinX); * @endcode * @see https://developer.apple.com/documentation/appkit/nstextblock */ @@ -54,15 +55,6 @@ namespace cocoon * @return The converted Objective-C result. */ Color border_color_for_edge(RectEdge edge) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextBlock borderColorForRectEdge:]`. - * @param rect_edge Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - Color border_color_for_rect_edge(CGRectEdge rect_edge) const; -#endif - /** * @brief Calls `-[NSTextBlock boundsRectForContentRect:inRect:textContainer:characterRange:]`. * @param content_rect Argument converted to the Objective-C parameter of the same role. @@ -102,57 +94,37 @@ namespace cocoon * @param edge Argument converted to the Objective-C parameter of the same role. */ void set_border_color(const Color& color, RectEdge edge) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextBlock setBorderColor:rectEdge:]`. - * @param border_color Argument converted to the Objective-C parameter of the same role. - * @param rect_edge Argument converted to the Objective-C parameter of the same role. - */ - void set_border_color(const Color& border_color, CGRectEdge rect_edge) const; -#endif - /** * @brief Calls `-[NSTextBlock setContentWidth:type:]`. * @details Convenience methods for content width in particular, using the above methods with dimension == NSTextBlockWidth - * @param content_width Argument converted to the Objective-C parameter of the same role. + * @param val Argument converted to the Objective-C parameter of the same role. * @param type Argument converted to the Objective-C parameter of the same role. */ - void set_content_width(double content_width, TextBlockValueType type) const; + void set_content_width(double val, TextBlockValueType type) const; /** * @brief Calls `-[NSTextBlock setValue:type:forDimension:]`. * @details Content size - * @param value Argument converted to the Objective-C parameter of the same role. + * @param val Argument converted to the Objective-C parameter of the same role. * @param type Argument converted to the Objective-C parameter of the same role. * @param dimension Argument converted to the Objective-C parameter of the same role. */ - void set_value(double value, TextBlockValueType type, TextBlockDimension dimension) const; + void set_value(double val, TextBlockValueType type, TextBlockDimension dimension) const; /** * @brief Calls `-[NSTextBlock setWidth:type:forLayer:]`. - * @details Margin, border, and padding - * @param width Argument converted to the Objective-C parameter of the same role. + * @param val Argument converted to the Objective-C parameter of the same role. * @param type Argument converted to the Objective-C parameter of the same role. * @param layer Argument converted to the Objective-C parameter of the same role. */ - void set_width(double width, TextBlockValueType type, TextBlockLayer layer) const; + void set_width(double val, TextBlockValueType type, TextBlockLayer layer) const; /** * @brief Calls `-[NSTextBlock setWidth:type:forLayer:edge:]`. + * @details Margin, border, and padding * @param val Argument converted to the Objective-C parameter of the same role. * @param type Argument converted to the Objective-C parameter of the same role. * @param layer Argument converted to the Objective-C parameter of the same role. * @param edge Argument converted to the Objective-C parameter of the same role. */ void set_width(double val, TextBlockValueType type, TextBlockLayer layer, RectEdge edge) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextBlock setWidth:type:forLayer:rectEdge:]`. - * @param width Argument converted to the Objective-C parameter of the same role. - * @param type Argument converted to the Objective-C parameter of the same role. - * @param layer Argument converted to the Objective-C parameter of the same role. - * @param rect_edge Argument converted to the Objective-C parameter of the same role. - */ - void set_width(double width, TextBlockValueType type, TextBlockLayer layer, CGRectEdge rect_edge) const; -#endif - /** * @brief Calls `-[NSTextBlock valueForDimension:]`. * @param dimension Argument converted to the Objective-C parameter of the same role. @@ -172,16 +144,6 @@ namespace cocoon * @return The converted Objective-C result. */ double width_for_layer(TextBlockLayer layer, RectEdge edge) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextBlock widthForLayer:rectEdge:]`. - * @param layer Argument converted to the Objective-C parameter of the same role. - * @param rect_edge Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - double width_for_layer(TextBlockLayer layer, CGRectEdge rect_edge) const; -#endif - /** * @brief Calls `-[NSTextBlock widthValueTypeForLayer:edge:]`. * @param layer Argument converted to the Objective-C parameter of the same role. @@ -189,16 +151,6 @@ namespace cocoon * @return The converted Objective-C result. */ TextBlockValueType width_value_type_for_layer(TextBlockLayer layer, RectEdge edge) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextBlock widthValueTypeForLayer:rectEdge:]`. - * @param layer Argument converted to the Objective-C parameter of the same role. - * @param rect_edge Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - TextBlockValueType width_value_type_for_layer(TextBlockLayer layer, CGRectEdge rect_edge) const; -#endif - /** * @brief Returns the `backgroundColor` property of `NSTextBlock`. * @details Colors diff --git a/include/generated/text_checking_result.h b/include/generated/text_checking_result.h index 042152e0..209291c1 100644 --- a/include/generated/text_checking_result.h +++ b/include/generated/text_checking_result.h @@ -16,7 +16,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextCheckingResult` (Foundation). - * @details An occurrence of textual content found during the analysis of a block of text, such as when matching a regular expression. On both iOS and macOS, instances of ''NSTextCheckingResult'' are returned by the ''NSRegularExpression'' class and the ''NSDataDetector'' class to indicate the discovery of content. In those cases, what is found may be a match for a regular expression or a date, address, phone number, and so on. In macOS, instances of 'NSTextCheckingResult' are returned by the \ object to describe the results of spelling, grammar, or text-substitution actions. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,7 +46,6 @@ namespace cocoon explicit TextCheckingResult(Adopt adopt); /** * @brief Calls `+[NSTextCheckingResult addressCheckingResultWithRange:components:]`. - * @details Creates and returns a text checking result with the specified address components. * @param range Argument converted to the Objective-C parameter of the same role. * @param components Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -55,7 +53,6 @@ namespace cocoon static TextCheckingResult address_checking_result_with_range(const Range& range, const std::map& components); /** * @brief Calls `+[NSTextCheckingResult correctionCheckingResultWithRange:replacementString:]`. - * @details Creates and returns a text checking result with the specified correction replacement string. * @param range Argument converted to the Objective-C parameter of the same role. * @param replacement_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -71,7 +68,6 @@ namespace cocoon static TextCheckingResult correction_checking_result_with_range(const Range& range, const std::string& replacement_string, const std::vector& alternative_strings); /** * @brief Calls `+[NSTextCheckingResult dashCheckingResultWithRange:replacementString:]`. - * @details Creates and returns a text checking result with the specified dash replacement string. * @param range Argument converted to the Objective-C parameter of the same role. * @param replacement_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -79,7 +75,6 @@ namespace cocoon static TextCheckingResult dash_checking_result_with_range(const Range& range, const std::string& replacement_string); /** * @brief Calls `+[NSTextCheckingResult dateCheckingResultWithRange:date:]`. - * @details Creates and returns a text checking result with the specified date. * @param range Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -87,7 +82,6 @@ namespace cocoon static TextCheckingResult date_checking_result_with_range(const Range& range, const Date& date); /** * @brief Calls `+[NSTextCheckingResult dateCheckingResultWithRange:date:timeZone:duration:]`. - * @details Creates and returns a text checking result with the specified date, time zone, and duration. * @param range Argument converted to the Objective-C parameter of the same role. * @param date Argument converted to the Objective-C parameter of the same role. * @param time_zone Argument converted to the Objective-C parameter of the same role. @@ -97,7 +91,6 @@ namespace cocoon static TextCheckingResult date_checking_result_with_range(const Range& range, const Date& date, const TimeZone& time_zone, double duration); /** * @brief Calls `+[NSTextCheckingResult grammarCheckingResultWithRange:details:]`. - * @details Creates and returns a text checking result with the specified grammar details. * @param range Argument converted to the Objective-C parameter of the same role. * @param details Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -105,7 +98,6 @@ namespace cocoon static TextCheckingResult grammar_checking_result_with_range(const Range& range, const std::vector>& details); /** * @brief Calls `+[NSTextCheckingResult linkCheckingResultWithRange:URL:]`. - * @details Creates and returns a text checking result with the specified URL. * @param range Argument converted to the Objective-C parameter of the same role. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -113,7 +105,7 @@ namespace cocoon static TextCheckingResult link_checking_result_with_range(const Range& range, const URL& url); /** * @brief Calls `+[NSTextCheckingResult orthographyCheckingResultWithRange:orthography:]`. - * @details Creates and returns a text checking result with the specified orthography. + * @details Methods for creating instances of the various types of results. * @param range Argument converted to the Objective-C parameter of the same role. * @param orthography Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -121,7 +113,6 @@ namespace cocoon static TextCheckingResult orthography_checking_result_with_range(const Range& range, const Orthography& orthography); /** * @brief Calls `+[NSTextCheckingResult phoneNumberCheckingResultWithRange:phoneNumber:]`. - * @details Creates and returns a text checking result with the specified phone number. * @param range Argument converted to the Objective-C parameter of the same role. * @param phone_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -129,7 +120,6 @@ namespace cocoon static TextCheckingResult phone_number_checking_result_with_range(const Range& range, const std::string& phone_number); /** * @brief Calls `+[NSTextCheckingResult quoteCheckingResultWithRange:replacementString:]`. - * @details Creates and returns a text checking result with the specified quote replacement string. * @param range Argument converted to the Objective-C parameter of the same role. * @param replacement_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -137,7 +127,6 @@ namespace cocoon static TextCheckingResult quote_checking_result_with_range(const Range& range, const std::string& replacement_string); /** * @brief Calls `-[NSTextCheckingResult rangeAtIndex:]`. - * @details Returns the range at the specified index. Passing a value of '0' always returns the value of the 'range' property. Additional ranges, if any, will have indexes from '1' to 'numberOfRanges-1'. * @param idx Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -150,7 +139,6 @@ namespace cocoon Range range_with_name(const std::string& name) const; /** * @brief Calls `+[NSTextCheckingResult regularExpressionCheckingResultWithRanges:count:regularExpression:]`. - * @details Creates and returns a text checking result with the specified regular expression data. * @param ranges Argument converted to the Objective-C parameter of the same role. * @param count Argument converted to the Objective-C parameter of the same role. * @param regular_expression Argument converted to the Objective-C parameter of the same role. @@ -159,7 +147,6 @@ namespace cocoon static TextCheckingResult regular_expression_checking_result_with_ranges(Range* ranges, std::uint64_t count, const RegularExpression& regular_expression); /** * @brief Calls `+[NSTextCheckingResult replacementCheckingResultWithRange:replacementString:]`. - * @details Creates and returns a text checking result with the specified replacement string. * @param range Argument converted to the Objective-C parameter of the same role. * @param replacement_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -167,21 +154,18 @@ namespace cocoon static TextCheckingResult replacement_checking_result_with_range(const Range& range, const std::string& replacement_string); /** * @brief Calls `-[NSTextCheckingResult resultByAdjustingRangesWithOffset:]`. - * @details Returns a new text checking result after adjusting the ranges as specified by the offset. * @param offset Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ TextCheckingResult result_by_adjusting_ranges_with_offset(std::int64_t offset) const; /** * @brief Calls `+[NSTextCheckingResult spellCheckingResultWithRange:]`. - * @details Creates and returns a text checking result with the range of a misspelled word. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static TextCheckingResult spell_checking_result_with_range(const Range& range); /** * @brief Calls `+[NSTextCheckingResult transitInformationCheckingResultWithRange:components:]`. - * @details Creates and returns a text checking result with the specified transit information. * @param range Argument converted to the Objective-C parameter of the same role. * @param components Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -189,13 +173,11 @@ namespace cocoon static TextCheckingResult transit_information_checking_result_with_range(const Range& range, const std::map& components); /** * @brief Returns the `URL` property of `NSTextCheckingResult`. - * @details The URL component of a type checking result. * @return The converted Objective-C result. */ URL url() const; /** * @brief Returns the `addressComponents` property of `NSTextCheckingResult`. - * @details The address dictionary of a type checking result. * @return The converted Objective-C result. */ std::map address_components() const; @@ -206,73 +188,64 @@ namespace cocoon std::vector alternative_strings() const; /** * @brief Returns the `components` property of `NSTextCheckingResult`. - * @details The components of a type checking result. * @return The converted Objective-C result. */ std::map components() const; /** * @brief Returns the `date` property of `NSTextCheckingResult`. - * @details The date component of a type checking result. * @return The converted Objective-C result. */ Date date() const; /** * @brief Returns the `duration` property of `NSTextCheckingResult`. - * @details The duration component of a type checking result. * @return The converted Objective-C result. */ double duration() const; /** * @brief Returns the `grammarDetails` property of `NSTextCheckingResult`. - * @details The details of a grammar checking result. * @return The converted Objective-C result. */ std::vector> grammar_details() const; /** * @brief Returns the `numberOfRanges` property of `NSTextCheckingResult`. - * @details Returns the number of ranges. A result must have at least one range, but may optionally have more (for example, to represent regular expression capture groups). + * @details A result must have at least one range, but may optionally have more (for example, to represent regular expression capture groups). The range at index 0 always matches the range property. Additional ranges, if any, will have indexes from 1 to numberOfRanges-1. rangeWithName: can be used with named regular expression capture groups. * @return The converted Objective-C result. */ std::uint64_t number_of_ranges() const; /** * @brief Returns the `orthography` property of `NSTextCheckingResult`. - * @details The detected orthography of a type checking result. + * @details Optional properties, used with certain types of results. * @return The converted Objective-C result. */ Orthography orthography() const; /** * @brief Returns the `phoneNumber` property of `NSTextCheckingResult`. - * @details The phone number of a type checking result. * @return The converted Objective-C result. */ std::string phone_number() const; /** * @brief Returns the `range` property of `NSTextCheckingResult`. - * @details Returns the range of the result that the receiver represents. * @return The converted Objective-C result. */ Range range() const; /** * @brief Returns the `regularExpression` property of `NSTextCheckingResult`. - * @details The regular expression of a type checking result. * @return The converted Objective-C result. */ RegularExpression regular_expression() const; /** * @brief Returns the `replacementString` property of `NSTextCheckingResult`. - * @details The replacement string of a type checking result. * @return The converted Objective-C result. */ std::string replacement_string() const; /** * @brief Returns the `resultType` property of `NSTextCheckingResult`. - * @details Returns the text checking result type that the receiver represents. + * @details Mandatory properties, used with all types of results. * @return The converted Objective-C result. */ TextCheckingType result_type() const; /** * @brief Returns the `timeZone` property of `NSTextCheckingResult`. - * @details The time zone component of a type checking result. * @return The converted Objective-C result. */ TimeZone time_zone() const; diff --git a/include/generated/text_container.h b/include/generated/text_container.h index 249265cd..279abb25 100644 --- a/include/generated/text_container.h +++ b/include/generated/text_container.h @@ -8,10 +8,7 @@ namespace cocoon { - class BezierPath; - class LayoutManager; class TextLayoutManager; - class TextView; /** * @brief C++ handle for the Objective-C class `NSTextContainer` (AppKit). @@ -33,9 +30,8 @@ namespace cocoon * auto container_size = text_container.container_size(); * text_container.set_height_tracks_text_view(true); * auto height_tracks_text_view = text_container.height_tracks_text_view(); - * text_container.set_layout_manager(cocoon::LayoutManager()); - * auto layout_manager = text_container.layout_manager(); - * text_container.replace_layout_manager(cocoon::LayoutManager()); + * text_container.set_line_break_mode(cocoon::LineBreakMode::WordWrapping); + * auto line_break_mode = text_container.line_break_mode(); * @endcode * @see https://developer.apple.com/documentation/appkit/nstextcontainer */ @@ -52,7 +48,6 @@ namespace cocoon explicit TextContainer(Adopt adopt); /** * @brief Calls `-[NSTextContainer lineFragmentRectForProposedRect:atIndex:writingDirection:remainingRect:]`. - * @details Returns the bounds of a line fragment rectangle inside the text container for the proposed rectangle. The bounds of the line fragment rectangle are determined by the intersection of 'proposedRect' and the text container's bounding rectangle defined by its ''NSTextContainer/size'' property. The regions defined by the ''NSTextContainer/exclusionPaths'' property are excluded from the return value. It is possible that 'proposedRect' can be divided into multiple line fragments due to exclusion paths. In that case, 'remainingRect' returns the remainder that can be passed in as the proposed rectangle for the next iteration. This method can be overridden by subclasses for further text container region customization. - Parameters: - proposedRect: A rectangle in which to lay out text proposed by the layout manager or text layout manager. - characterIndex: The character location inside the text storage for the line fragment being processed. - baseWritingDirection: The direction of advancement for line fragments inside a visual horizontal line. The values passed into the method are either ''NSWritingDirection/leftToRight'' or ''NSWritingDirection/rightToLeft''. - remainingRect: The remainder of the proposed rectangle that was excluded from the returned rectangle. It can be passed in as the proposed rectangle for the next iteration. - Returns: The bounds of the line fragment rect. * @param proposed_rect Argument converted to the Objective-C parameter of the same role. * @param character_index Argument converted to the Objective-C parameter of the same role. * @param base_writing_direction Argument converted to the Objective-C parameter of the same role. @@ -69,11 +64,6 @@ namespace cocoon * @return The converted Objective-C result. */ Rect line_fragment_rect_for_proposed_rect(const Rect& proposed_rect, LineSweepDirection sweep_direction, LineMovementDirection movement_direction, Rect* remaining_rect) const; - /** - * @brief Calls `-[NSTextContainer replaceLayoutManager:]`. - * @param new_layout_manager Argument converted to the Objective-C parameter of the same role. - */ - void replace_layout_manager(const LayoutManager& new_layout_manager) const; /** * @brief Returns the `containerSize` property of `NSTextContainer`. * @return The converted Objective-C result. @@ -84,119 +74,73 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_container_size(const Size& value) const; - /** - * @brief Returns the `exclusionPaths` property of `NSTextContainer`. - * @details An array of path objects that represents the regions where text doesn't display in the text container. The default value is an empty array. - * @return The converted Objective-C result. - */ - std::vector exclusion_paths() const; - /** - * @brief Sets the `exclusionPaths` property of `NSTextContainer`. - * @details An array of path objects that represents the regions where text doesn't display in the text container. The default value is an empty array. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_exclusion_paths(const std::vector& value) const; /** * @brief Returns the `heightTracksTextView` property of `NSTextContainer`. - * @details A Boolean that controls whether the text container adjusts the height of its bounding rectangle when its text view resizes. When the value of this property is \, the text container adjusts its height when the height of its text view changes. The default value of this property is \. For more information about size tracking, see [Text System Storage Layer Overview](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/TextStorageLayer/TextStorageLayer.html\#//apple_ref/doc/uid/10000087i). \#\# See Also - ''NSTextContainer/size'' * @return The converted Objective-C result. */ bool height_tracks_text_view() const; /** * @brief Sets the `heightTracksTextView` property of `NSTextContainer`. - * @details A Boolean that controls whether the text container adjusts the height of its bounding rectangle when its text view resizes. When the value of this property is \, the text container adjusts its height when the height of its text view changes. The default value of this property is \. For more information about size tracking, see [Text System Storage Layer Overview](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/TextStorageLayer/TextStorageLayer.html\#//apple_ref/doc/uid/10000087i). \#\# See Also - ''NSTextContainer/size'' * @param value Argument converted to the Objective-C parameter of the same role. */ void set_height_tracks_text_view(bool value) const; - /** - * @brief Returns the `layoutManager` property of `NSTextContainer`. - * @return The converted Objective-C result. - */ - LayoutManager layout_manager() const; - /** - * @brief Sets the `layoutManager` property of `NSTextContainer`. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_layout_manager(const LayoutManager& value) const; /** * @brief Returns the `lineBreakMode` property of `NSTextContainer`. - * @details The behavior of the last line inside the text container. The ''NSLineBreakMode'' constants specify what happens when a line is too long for its container. For example, wrapping can occur on word boundaries (the default) or character boundaries, or the line can be clipped or truncated. The default value of this property is ''NSLineBreakMode/byWordWrapping''. * @return The converted Objective-C result. */ LineBreakMode line_break_mode() const; /** * @brief Sets the `lineBreakMode` property of `NSTextContainer`. - * @details The behavior of the last line inside the text container. The ''NSLineBreakMode'' constants specify what happens when a line is too long for its container. For example, wrapping can occur on word boundaries (the default) or character boundaries, or the line can be clipped or truncated. The default value of this property is ''NSLineBreakMode/byWordWrapping''. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_line_break_mode(LineBreakMode value) const; /** * @brief Returns the `lineFragmentPadding` property of `NSTextContainer`. - * @details The value for the text inset within line fragment rectangles. The padding appears at the beginning and end of the line fragment rectangles. The layout manager and text layout manager use this value to determine the layout width. The default value of this property is '5.0'. Line fragment padding is not designed to express text margins. Instead, you should use insets on your text view, adjust the paragraph margin attributes, or change the position of the text view within its superview. \#\# See Also - ''lineFragmentRect(forProposedRect:at:writingDirection:remaining:)'' * @return The converted Objective-C result. */ double line_fragment_padding() const; /** * @brief Sets the `lineFragmentPadding` property of `NSTextContainer`. - * @details The value for the text inset within line fragment rectangles. The padding appears at the beginning and end of the line fragment rectangles. The layout manager and text layout manager use this value to determine the layout width. The default value of this property is '5.0'. Line fragment padding is not designed to express text margins. Instead, you should use insets on your text view, adjust the paragraph margin attributes, or change the position of the text view within its superview. \#\# See Also - ''lineFragmentRect(forProposedRect:at:writingDirection:remaining:)'' * @param value Argument converted to the Objective-C parameter of the same role. */ void set_line_fragment_padding(double value) const; /** * @brief Returns the `maximumNumberOfLines` property of `NSTextContainer`. - * @details The maximum number of lines that the text container can store. The layout manager and text layout manager use the value of this property to determine the maximum number of lines associated with the text container. The default value of this property is '0', which indicates that there is no limit. * @return The converted Objective-C result. */ std::uint64_t maximum_number_of_lines() const; /** * @brief Sets the `maximumNumberOfLines` property of `NSTextContainer`. - * @details The maximum number of lines that the text container can store. The layout manager and text layout manager use the value of this property to determine the maximum number of lines associated with the text container. The default value of this property is '0', which indicates that there is no limit. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum_number_of_lines(std::uint64_t value) const; /** * @brief Returns the `simpleRectangularTextContainer` property of `NSTextContainer`. - * @details A Boolean that indicates whether the text container's region is a rectangle with no holes or gaps, and whose edges are parallel to the text view's coordinate system axes. The value of this property is \ when the text container's region is a rectangle with no holes or gaps and the edges are parallel to the text view's coordinate system axes. The default value of this property is \ when the ''NSTextContainer/exclusionPaths'' property contains one or more items, when the ''NSTextContainer/maximumNumberOfLines'' property is not zero, or when you override the ''NSTextContainer/lineFragmentRect(forProposedRect:at:writingDirection:remaining:)'' method. Otherwise, the default value is \. * @return The converted Objective-C result. */ bool is_simple_rectangular_text_container() const; /** * @brief Returns the `size` property of `NSTextContainer`. - * @details The size of the text container's bounding rectangle. This property defines the maximum size for the layout area returned from ''NSTextContainer/lineFragmentRect(forProposedRect:at:writingDirection:remaining:)''. A value of '0.0' or less means no limitation. If you don't specify an explicit size when you initialize a text container, the system uses a default large size of ('10000000.0', '10000000.0'). * @return The converted Objective-C result. */ Size size() const; /** * @brief Sets the `size` property of `NSTextContainer`. - * @details The size of the text container's bounding rectangle. This property defines the maximum size for the layout area returned from ''NSTextContainer/lineFragmentRect(forProposedRect:at:writingDirection:remaining:)''. A value of '0.0' or less means no limitation. If you don't specify an explicit size when you initialize a text container, the system uses a default large size of ('10000000.0', '10000000.0'). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_size(const Size& value) const; /** * @brief Returns the `textLayoutManager` property of `NSTextContainer`. - * @details The ''NSTextLayoutManager'' owning the text container. When non-nil, the legacy 'layoutManager' should be 'nil'. * @return The converted Objective-C result. */ TextLayoutManager text_layout_manager() const; - /** - * @brief Returns the `textView` property of `NSTextContainer`. - * @return The converted Objective-C result. - */ - TextView text_view() const; - /** - * @brief Sets the `textView` property of `NSTextContainer`. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_text_view(const TextView& value) const; /** * @brief Returns the `widthTracksTextView` property of `NSTextContainer`. - * @details A Boolean that controls whether the text container adjusts the width of its bounding rectangle when its text view resizes. When the value of this property is \, the text container adjusts its width when the width of its text view changes. The default value of this property is \. For more information about size tracking, see [Text System Storage Layer Overview](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/TextStorageLayer/TextStorageLayer.html\#//apple_ref/doc/uid/10000087i). \#\# See Also - ''NSTextContainer/size'' * @return The converted Objective-C result. */ bool width_tracks_text_view() const; /** * @brief Sets the `widthTracksTextView` property of `NSTextContainer`. - * @details A Boolean that controls whether the text container adjusts the width of its bounding rectangle when its text view resizes. When the value of this property is \, the text container adjusts its width when the width of its text view changes. The default value of this property is \. For more information about size tracking, see [Text System Storage Layer Overview](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/TextStorageLayer/TextStorageLayer.html\#//apple_ref/doc/uid/10000087i). \#\# See Also - ''NSTextContainer/size'' * @param value Argument converted to the Objective-C parameter of the same role. */ void set_width_tracks_text_view(bool value) const; diff --git a/include/generated/text_content_manager.h b/include/generated/text_content_manager.h index 384d7f56..3151ccbc 100644 --- a/include/generated/text_content_manager.h +++ b/include/generated/text_content_manager.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextContentManager` (AppKit). - * @details An abstract class that defines the interface and a default implementation for managing the text document contents. The concrete subclass overrides ''NSTextElementProvider'' for managing the content backing store. It is the root object that strongly references the rest of objects in the TextKit network via an array of ''NSTextLayoutManager''. It manages the editing transaction by tracking the ''NSTextLayoutManager'' that is active and focused for editing. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -53,87 +52,73 @@ namespace cocoon explicit TextContentManager(Adopt adopt); /** * @brief Calls `-[NSTextContentManager addTextLayoutManager:]`. - * @details Adds the text layout manager you provide to the list of layout managers. - Parameters: - textLayoutManager: The text layout manager to add. * @param text_layout_manager Argument converted to the Objective-C parameter of the same role. */ void add_text_layout_manager(const TextLayoutManager& text_layout_manager) const; /** * @brief Calls `-[NSTextContentManager performEditingTransactionUsingBlock:]`. - * @details Performs an editing transaction and invokes a block upon completion. Invoked by ''primaryTextLayoutManager'' controlling the active editing transaction. Can be nested. The outermost transaction toggles ''hasEditingTransaction'' and sends synchronization messages if enabled after invoking 'transaction'. - Parameters: - transaction: The block to execute within the editing transaction. * @param transaction Argument converted to the Objective-C parameter of the same role. */ void perform_editing_transaction_using_block(std::function transaction) const; /** * @brief Calls `-[NSTextContentManager recordEditActionInRange:newTextRange:]`. - * @details Records information about an edit action to the transaction. 'originalTextRange' is the range edited before the action, and 'newTextRange' is the corresponding range after the action. The concrete subclass should invoke this method for each edit action. - Parameters: - originalTextRange: The range before the edit. - newTextRange: The corresponding range after the edit. * @param original_text_range Argument converted to the Objective-C parameter of the same role. * @param new_text_range Argument converted to the Objective-C parameter of the same role. */ void record_edit_action_in_range(const TextRange& original_text_range, const TextRange& new_text_range) const; /** * @brief Calls `-[NSTextContentManager removeTextLayoutManager:]`. - * @details Removes the text layout manager you specify from the list of layout managers. - Parameters: - textLayoutManager: The text layout manager to remove. * @param text_layout_manager Argument converted to the Objective-C parameter of the same role. */ void remove_text_layout_manager(const TextLayoutManager& text_layout_manager) const; /** * @brief Calls `-[NSTextContentManager synchronizeTextLayoutManagers:]`. - * @details Synchronizes changes to all nonprimary text layout managers. If 'completionHandler' is 'nil', this method performs the operation synchronously. The framework passes any error to the 'completionHandler'. The method blocks (or fails, if synchronous) when there's an active transaction. - Parameters: - completionHandler: A completion handler that runs on success, or to handle error conditions. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void synchronize_text_layout_managers(std::function completion_handler) const; /** * @brief Calls `-[NSTextContentManager textElementsForRange:]`. - * @details Returns an array of text elements that intersect with the range you specify. This method can return a set of elements that don't fill the entire range if the entire range isn't synchronously available. Uses ''NSTextElementProvider/enumerateTextElements(from:options:using:)'' to fill the array. - Parameters: - range: An ''NSTextRange'' that describes the range of text to process. - Returns: An array of ''NSTextElement''. * @param range Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector text_elements_for_range(const TextRange& range) const; /** * @brief Returns the `automaticallySynchronizesTextLayoutManagers` property of `NSTextContentManager`. - * @details Determines if the framework should automatically synchronize all text layout managers when exiting an editing transaction. The default value is 'true'. * @return The converted Objective-C result. */ bool automatically_synchronizes_text_layout_managers() const; /** * @brief Sets the `automaticallySynchronizesTextLayoutManagers` property of `NSTextContentManager`. - * @details Determines if the framework should automatically synchronize all text layout managers when exiting an editing transaction. The default value is 'true'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_automatically_synchronizes_text_layout_managers(bool value) const; /** * @brief Returns the `automaticallySynchronizesToBackingStore` property of `NSTextContentManager`. - * @details Determines whether to automatically synchronize with the backing store when an editing transaction finishes. The default value is 'false'. * @return The converted Objective-C result. */ bool automatically_synchronizes_to_backing_store() const; /** * @brief Sets the `automaticallySynchronizesToBackingStore` property of `NSTextContentManager`. - * @details Determines whether to automatically synchronize with the backing store when an editing transaction finishes. The default value is 'false'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_automatically_synchronizes_to_backing_store(bool value) const; /** * @brief Returns the `hasEditingTransaction` property of `NSTextContentManager`. - * @details Indicates there's an active editing transaction from the primary text layout manager. The synchronization operations to non-primary text layout managers and the backing store block (or fail when synchronous) while this property is 'true'. Non-primary text layout managers should avoid accessing the elements while this is 'true'. KVO-compliant. * @return The converted Objective-C result. */ bool has_editing_transaction() const; /** * @brief Returns the `primaryTextLayoutManager` property of `NSTextContentManager`. - * @details The primary text layout manager for this content. The primary ''NSTextLayoutManager'' interacts with the user, allowing edits. Setting this property to an ''NSTextLayoutManager'' not in ''textLayoutManagers'' resets it to 'nil'. It automatically synchronizes pending edits before switching to a new primary object. The operation is synchronous. This property is KVO-compliant. * @return The converted Objective-C result. */ TextLayoutManager primary_text_layout_manager() const; /** * @brief Sets the `primaryTextLayoutManager` property of `NSTextContentManager`. - * @details The primary text layout manager for this content. The primary ''NSTextLayoutManager'' interacts with the user, allowing edits. Setting this property to an ''NSTextLayoutManager'' not in ''textLayoutManagers'' resets it to 'nil'. It automatically synchronizes pending edits before switching to a new primary object. The operation is synchronous. This property is KVO-compliant. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_primary_text_layout_manager(const TextLayoutManager& value) const; /** * @brief Returns the `textLayoutManagers` property of `NSTextContentManager`. - * @details The array of text layout managers associated with this text content manager. This property is KVO-compliant. * @return The converted Objective-C result. */ std::vector text_layout_managers() const; diff --git a/include/generated/text_content_storage.h b/include/generated/text_content_storage.h index c7a9d427..981e1d81 100644 --- a/include/generated/text_content_storage.h +++ b/include/generated/text_content_storage.h @@ -15,7 +15,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextContentStorage` (AppKit). - * @details A concrete object for managing the document's text content and generating the text elements necessary for layout. An ''NSTextContentStorage'' object provides the backing store for document content. It stores the text in an attributed string object, and defaults to using an ''NSTextStorage'' object. It also maps portions of the text to ''NSTextElement'' objects to organize the text into paragraphs, lists, and other common element types found in text content. During layout, TextKit uses these elements to lay out and render the content into one or more rendering surfaces. 'NSTextContentStorage' is a concrete subclass of ''NSTextContentManager'' providing support for 'NSAttributedString' backing store. It also implements 'NSTextStorageObserving' participating as a client of 'NSTextStorage'. The facility only supports a single 'NSTextContentStorage' associated with a text storage. When ''NSTextStorage'' is non-nil, ''attributedString'' is ignored. By default, 'NSTextContentStorage' is initialized with 'NSTextStorage' as the backing store. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref TextContentManager. * @@ -52,7 +51,6 @@ namespace cocoon explicit TextContentStorage(Adopt adopt); /** * @brief Calls `-[NSTextContentStorage adjustedRangeFromRange:forEditingTextSelection:]`. - * @details Returns the text range, if any, in the backing store that required manual adjustment after editing. Should be implemented if the location backing store requires manual adjustment after editing. When 'textRange' is intersecting or following the current edited range, the method returns the range adjusted for the modification in the editing session. Returns 'nil' when no adjustment is necessary. - Parameters: - textRange: The range to adjust. - forEditingTextSelection: Indicates if 'textRange' is for the text selection associated with the edit session. - Returns: The adjusted range, or 'nil' if no adjustment is necessary. * @param text_range Argument converted to the Objective-C parameter of the same role. * @param for_editing_text_selection Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -60,14 +58,12 @@ namespace cocoon TextRange adjusted_range_from_range(const TextRange& text_range, bool for_editing_text_selection) const; /** * @brief Calls `-[NSTextContentStorage attributedStringForTextElement:]`. - * @details Returns a new attributed string for the text element. Returns 'nil' if 'textElement' cannot be mapped to 'NSAttributedString'. - Parameters: - textElement: The text element to convert. - Returns: An attributed string representation, or 'nil' if unmappable. * @param text_element Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ AttributedString attributed_string_for_text_element(const TextElement& text_element) const; /** * @brief Calls `-[NSTextContentStorage locationFromLocation:withOffset:]`. - * @details Returns a new text location object based on an existing location and offset you provide. The offset value could be positive or negative indicating the logical direction. Could return 'nil' when the inputs don't produce any legal location (i.e. out of bounds index). - Parameters: - location: The base location. - offset: The offset from the base location. - Returns: A new location, or 'nil' if the result would be out of bounds. * @param location Argument converted to the Objective-C parameter of the same role. * @param offset Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -75,7 +71,6 @@ namespace cocoon Object location_from_location(const Object& location, std::int64_t offset) const; /** * @brief Calls `-[NSTextContentStorage offsetFromLocation:toLocation:]`. - * @details Returns the number of characters between the specified locations. The return value could be positive or negative. Could return 'NSNotFound' when the offset cannot be represented in an integer value (i.e. locations are not in the same document). - Parameters: - from: The starting location. - to: The ending location. - Returns: The signed offset, or \ if the locations are not in the same document. * @param from Argument converted to the Objective-C parameter of the same role. * @param to Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -83,32 +78,27 @@ namespace cocoon std::int64_t offset_from_location(const Object& from, const Object& to) const; /** * @brief Calls `-[NSTextContentStorage textElementForAttributedString:]`. - * @details Returns the text element corresponding to the attributed string. Returns 'nil' when 'attributedString' contains attributes not mappable to ''NSTextElement''. - Parameters: - attributedString: The attributed string to convert. - Returns: A text element, or 'nil' if the attributes are unmappable. * @param attributed_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ TextElement text_element_for_attributed_string(const AttributedString& attributed_string) const; /** * @brief Returns the `attributedString` property of `NSTextContentStorage`. - * @details An attributed string that contains the contents of the document. KVO-compliant. * @return The converted Objective-C result. */ AttributedString attributed_string() const; /** * @brief Sets the `attributedString` property of `NSTextContentStorage`. - * @details An attributed string that contains the contents of the document. KVO-compliant. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attributed_string(const AttributedString& value) const; /** * @brief Returns the `includesTextListMarkers` property of `NSTextContentStorage`. - * @details When 'true', 'NSTextContentStorage' assumes the paragraph with 'NSTextList' includes the text list marker string. Utilizes 'NSTextList.includesTextListMarkers' as the default value. * @return The converted Objective-C result. */ bool includes_text_list_markers() const; /** * @brief Sets the `includesTextListMarkers` property of `NSTextContentStorage`. - * @details When 'true', 'NSTextContentStorage' assumes the paragraph with 'NSTextList' includes the text list marker string. Utilizes 'NSTextList.includesTextListMarkers' as the default value. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_includes_text_list_markers(bool value) const; diff --git a/include/generated/text_element.h b/include/generated/text_element.h index 3d276732..39133179 100644 --- a/include/generated/text_element.h +++ b/include/generated/text_element.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextElement` (AppKit). - * @details An abstract base class that represents the smallest units of text layout such as paragraphs or attachments. A text element is associated with an ''NSTextContentManager''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,43 +47,36 @@ namespace cocoon explicit TextElement(Adopt adopt); /** * @brief Returns the `childElements` property of `NSTextElement`. - * @details An array of zero or more child text elements. A concrete 'NSTextElement' subclass can be structured in a tree. An element can have zero or more child elements. * @return The converted Objective-C result. */ std::vector child_elements() const; /** * @brief Returns the `elementRange` property of `NSTextElement`. - * @details A range value that represents the range of the element inside the document. * @return The converted Objective-C result. */ TextRange element_range() const; /** * @brief Sets the `elementRange` property of `NSTextElement`. - * @details A range value that represents the range of the element inside the document. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_element_range(const TextRange& value) const; /** * @brief Returns the `isRepresentedElement` property of `NSTextElement`. - * @details A Boolean value that indicates whether this element is in the text layout. When 'true', the element is enumerated by ''NSTextContentManager''. * @return The converted Objective-C result. */ bool is_represented_element() const; /** * @brief Returns the `parentElement` property of `NSTextElement`. - * @details A value that represents the parent element if this text element is a child of an enclosing element. * @return The converted Objective-C result. */ TextElement parent_element() const; /** * @brief Returns the `textContentManager` property of `NSTextElement`. - * @details The value that represents the current content manager. A text element can migrate between text content managers. * @return The converted Objective-C result. */ TextContentManager text_content_manager() const; /** * @brief Sets the `textContentManager` property of `NSTextElement`. - * @details The value that represents the current content manager. A text element can migrate between text content managers. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_content_manager(const TextContentManager& value) const; diff --git a/include/generated/text_field.h b/include/generated/text_field.h index 6241ecb5..051964f9 100644 --- a/include/generated/text_field.h +++ b/include/generated/text_field.h @@ -210,24 +210,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_bezeled(bool value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `borderShape` property of `NSTextField`. - * @details Set border shape 'NSControlBorderShapeAutomatic' sets text field or subclass to default system shape. 'NSControlBorderShapeCircle' sets text field or subclass to 'NSControlBorderShapeAutomatic'. - * @return The converted Objective-C result. - */ - ControlBorderShape border_shape() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `borderShape` property of `NSTextField`. - * @details Set border shape 'NSControlBorderShapeAutomatic' sets text field or subclass to default system shape. 'NSControlBorderShapeCircle' sets text field or subclass to 'NSControlBorderShapeAutomatic'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_border_shape(ControlBorderShape value) const; -#endif - /** * @brief Returns the `bordered` property of `NSTextField`. * @return The converted Objective-C result. diff --git a/include/generated/text_layout_fragment.h b/include/generated/text_layout_fragment.h index 5b483e41..ac0e6ca6 100644 --- a/include/generated/text_layout_fragment.h +++ b/include/generated/text_layout_fragment.h @@ -51,26 +51,22 @@ namespace cocoon explicit TextLayoutFragment(Adopt adopt); /** * @brief Calls `-[NSTextLayoutFragment drawAtPoint:inContext:]`. - * @details Renders the visual representation of this element in the specified graphics context. - Parameters: - point: The origin as a \. - context: The graphics context to draw into. * @param point Argument converted to the Objective-C parameter of the same role. * @param context Argument converted to the Objective-C parameter of the same role. */ void draw_at_point(const Point& point, const CGContext& context) const; /** * @brief Calls `-[NSTextLayoutFragment frameForTextAttachmentAtLocation:]`. - * @details Returns the frame in the text layout fragment coordinate system for the attachment at the location you specify. Returns \ if 'location' is not within any attachment or the state is not 'NSTextLayoutFragmentStateLayoutAvailable'. - Parameters: - location: The document location of the attachment. - Returns: The frame of the attachment, or 'CGRectZero'. * @param location Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Rect frame_for_text_attachment_at_location(const Object& location) const; /** * @brief Calls `-[NSTextLayoutFragment invalidateLayout]`. - * @details Invalidates any layout information associated with the text layout fragment. */ void invalidate_layout() const; /** * @brief Calls `-[NSTextLayoutFragment textLineFragmentForTextLocation:isUpstreamAffinity:]`. - * @details Returns a text line fragment from a specific text location in the document. Set 'isUpstreamAffinity' to 'true' to find a text fragment by its element range end location, such as when you enumerate over line fragments in reverse order. Set 'isUpstreamAffinity' to 'false' to find a text fragment that contains 'textLocation'. - Parameters: - textLocation: The text location to search for. - isUpstreamAffinity: When the location is at the end of a text line fragment (and the beginning of another), 'true' chooses the one ending with the location; 'false' chooses the following. - Returns: The matching line fragment, or 'nil'. * @param text_location Argument converted to the Objective-C parameter of the same role. * @param is_upstream_affinity Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -78,7 +74,6 @@ namespace cocoon TextLineFragment text_line_fragment_for_text_location(const Object& text_location, bool is_upstream_affinity) const; /** * @brief Calls `-[NSTextLayoutFragment textLineFragmentForVerticalOffset:requiresExactMatch:]`. - * @details Returns the text line fragment for the vertical offset you provide, or the closest text line fragment beyond the vertical offset. Set 'requiresExactMatch' to 'true' to find the text line fragment that contains the vertical offset, or set 'requiresExactMatch' to 'false' to find the closest text line fragment matching or beyond the vertical offset. Returns 'nil' if there isn't a match. - Parameters: - verticalOffset: The vertical offset to search for. - requiresExactMatch: When 'false', returns the closest line fragment beyond 'verticalOffset' if no line fragment contains it. - Returns: The matching line fragment, or 'nil'. * @param vertical_offset Argument converted to the Objective-C parameter of the same role. * @param requires_exact_match Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -86,85 +81,71 @@ namespace cocoon TextLineFragment text_line_fragment_for_vertical_offset(double vertical_offset, bool requires_exact_match) const; /** * @brief Returns the `bottomMargin` property of `NSTextLayoutFragment`. - * @details The amount of space reserved during paragraph layout between the bottom of the last line in the paragraph and the bottom of the text layout fragment. * @return The converted Objective-C result. */ double bottom_margin() const; /** * @brief Returns the `layoutFragmentFrame` property of `NSTextLayoutFragment`. - * @details The rectangle the framework uses for tiling the layout fragment inside the target layout coordinate system. Typically in an ''NSTextContainer'' coordinate system. * @return The converted Objective-C result. */ Rect layout_fragment_frame() const; /** * @brief Returns the `layoutQueue` property of `NSTextLayoutFragment`. - * @details The queue on which the framework dispatches layout operations. When non-nil, the layout operation is dispatched to the queue asynchronously. * @return The converted Objective-C result. */ OperationQueue layout_queue() const; /** * @brief Sets the `layoutQueue` property of `NSTextLayoutFragment`. - * @details The queue on which the framework dispatches layout operations. When non-nil, the layout operation is dispatched to the queue asynchronously. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_layout_queue(const OperationQueue& value) const; /** * @brief Returns the `leadingPadding` property of `NSTextLayoutFragment`. - * @details The amount of margin space reserved during paragraph layout between the leading edge of the text layout fragment and the start of the lines in the paragraph. The leading edge is according to the primary writing direction of the paragraph. * @return The converted Objective-C result. */ double leading_padding() const; /** * @brief Returns the `rangeInElement` property of `NSTextLayoutFragment`. - * @details The range inside the text element relative to the document origin. * @return The converted Objective-C result. */ TextRange range_in_element() const; /** * @brief Returns the `renderingSurfaceBounds` property of `NSTextLayoutFragment`. - * @details The bounds defining the area required for rendering the contents. The coordinate system is relative to ''layoutFragmentFrame''. The coordinate system is vertically flipped, meaning origin ('{0,0}') is at the upper-left corner. The size should be larger than 'layoutFragmentFrame.size'. The origin could be in the negative coordinate since the rendering could be stretched out of 'layoutFragmentFrame'. Only valid when ''state'' is greater than 'NSTextLayoutFragmentStateEstimatedUsageBounds'. * @return The converted Objective-C result. */ Rect rendering_surface_bounds() const; /** * @brief Returns the `state` property of `NSTextLayoutFragment`. - * @details The layout information state. KVO-compliant. * @return The converted Objective-C result. */ TextLayoutFragmentState state() const; /** * @brief Returns the `textAttachmentViewProviders` property of `NSTextLayoutFragment`. - * @details The attachment view providers associated with the text layout fragment. The property contents are only valid with 'NSTextLayoutFragmentStateLayoutAvailable'. * @return The converted Objective-C result. */ std::vector text_attachment_view_providers() const; /** * @brief Returns the `textElement` property of `NSTextLayoutFragment`. - * @details The parent text element. * @return The converted Objective-C result. */ TextElement text_element() const; /** * @brief Returns the `textLayoutManager` property of `NSTextLayoutFragment`. - * @details The text layout manager for this text layout fragment. * @return The converted Objective-C result. */ TextLayoutManager text_layout_manager() const; /** * @brief Returns the `textLineFragments` property of `NSTextLayoutFragment`. - * @details An array of text line fragments. Valid when ''state'' is 'NSTextLayoutFragmentStateLayoutAvailable'. KVO-compliant. * @return The converted Objective-C result. */ std::vector text_line_fragments() const; /** * @brief Returns the `topMargin` property of `NSTextLayoutFragment`. - * @details The amount of space reserved during paragraph layout between the top of the text layout fragment and the top of the first line in the paragraph. * @return The converted Objective-C result. */ double top_margin() const; /** * @brief Returns the `trailingPadding` property of `NSTextLayoutFragment`. - * @details The amount of margin space reserved during paragraph layout between the end of the lines in the paragraph and the trailing edge of the text layout fragment. The trailing edge is according to the primary writing direction of the paragraph. * @return The converted Objective-C result. */ double trailing_padding() const; diff --git a/include/generated/text_layout_manager.h b/include/generated/text_layout_manager.h index 75423242..599daa21 100644 --- a/include/generated/text_layout_manager.h +++ b/include/generated/text_layout_manager.h @@ -10,8 +10,6 @@ namespace cocoon { class AttributedString; class OperationQueue; - class TextAttachment; - class TextAttachmentViewProvider; class TextContainer; class TextContentManager; class TextElement; @@ -23,7 +21,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextLayoutManager` (AppKit). - * @details The primary class that you use to manage text layout and presentation for custom text displays. 'NSTextLayoutManager' is the centerpiece of the TextKit object network maintaining the layout geometry through an array of ''NSTextContainer'' objects. It lays out results using ''NSTextLayoutFragment'' and ''NSTextElement'' objects vended from a ''NSTextContentManager'' that participates in the content layout process. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -32,7 +29,6 @@ namespace cocoon * * cocoon::TextLayoutManager text_layout_manager; * text_layout_manager.set_layout_queue(cocoon::OperationQueue()); - * text_layout_manager.cache_text_attachment_view_provider_for_text_attachment().connect([](auto&&...) {}); * @endcode * * @par Common tasks @@ -48,7 +44,6 @@ namespace cocoon * text_layout_manager.ensure_layout_for_bounds({{0, 0}, {100, 100}}); * text_layout_manager.ensure_layout_for_range(cocoon::TextRange()); * text_layout_manager.invalidate_layout_for_range(cocoon::TextRange()); - * text_layout_manager.cache_text_attachment_view_provider_for_text_attachment().connect([](cocoon::TextAttachmentViewProvider a0, cocoon::TextAttachment a1) {}); * @endcode * @see https://developer.apple.com/documentation/appkit/nstextlayoutmanager */ @@ -63,7 +58,6 @@ namespace cocoon explicit TextLayoutManager(Adopt adopt); /** * @brief Calls `-[NSTextLayoutManager addRenderingAttribute:value:forTextRange:]`. - * @details Adds a rendering attribute for the range you specify. Passing 'nil' for value indicates overriding the specified attribute by removing it from the final attributes passed to the layout and rendering engine. This is a convenience over ''setRenderingAttributes:forTextRange:''. - Parameters: - renderingAttribute: The \ attribute to add. - value: The attribute value, or 'nil' to remove. - textRange: The range to apply the attribute to. * @param rendering_attribute Argument converted to the Objective-C parameter of the same role. * @param value Argument converted to the Objective-C parameter of the same role. * @param text_range Argument converted to the Objective-C parameter of the same role. @@ -71,19 +65,16 @@ namespace cocoon void add_rendering_attribute(const std::string& rendering_attribute, const Object& value, const TextRange& text_range) const; /** * @brief Calls `-[NSTextLayoutManager ensureLayoutForBounds:]`. - * @details Performs the layout for filling bounds inside the last text container. - Parameters: - bounds: A \ that describes the layout bounds. * @param bounds Argument converted to the Objective-C parameter of the same role. */ void ensure_layout_for_bounds(const Rect& bounds) const; /** * @brief Calls `-[NSTextLayoutManager ensureLayoutForRange:]`. - * @details Performs the layout for the specified text range. - Parameters: - range: The text range to lay out. * @param range Argument converted to the Objective-C parameter of the same role. */ void ensure_layout_for_range(const TextRange& range) const; /** * @brief Calls `-[NSTextLayoutManager enumerateRenderingAttributesFromLocation:reverse:usingBlock:]`. - * @details Enumerates the rendering attributes from the specified location. It enumerates only ranges with rendering attributes specified. Returning 'false' from block breaks out of the enumeration. Rendering attributes override the document text attributes stored in ''NSTextParagraph'' objects supplied by ''NSTextContentManager''. ''NSTextLayoutFragment'' associated with a text paragraph applies the overriding attributes before executing layout. Specifying \ to an attribute indicates removing it from the document attributes. Rendering attributes are invalidated upon re-layout of the text layout fragment that they belong to. - Parameters: - location: The starting location. - reverse: Whether to enumerate in reverse. - block: A block called for each range with rendering attributes. Return 'false' to stop. * @param location Argument converted to the Objective-C parameter of the same role. * @param reverse Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. @@ -91,7 +82,6 @@ namespace cocoon void enumerate_rendering_attributes_from_location(const Object& location, bool reverse, std::function, TextRange)> block) const; /** * @brief Calls `-[NSTextLayoutManager enumerateTextLayoutFragmentsFromLocation:options:usingBlock:]`. - * @details Enumerates the text layout fragments starting at the specified location. If 'location' is 'nil', it assumes 'self.textContentManager.documentRange.location'; uses 'documentRange.endLocation' for reverse enumeration. When enumerating backward, it starts with the fragment preceding the one containing 'location'. If enumerated at least one fragment, it returns the edge of the enumerated range. Note that the enumerated range might not match the range of the last element returned. Returning 'false' from block breaks out of the enumeration. - Parameters: - location: The starting location, or 'nil' for the document edge. - options: Enumeration options controlling direction and behavior. - block: A block called for each layout fragment. Return 'false' to stop. - Returns: The edge of the enumerated range, or 'nil'. * @param location Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param block Argument converted to the Objective-C parameter of the same role. @@ -100,7 +90,6 @@ namespace cocoon Object enumerate_text_layout_fragments_from_location(const Object& location, TextLayoutFragmentEnumerationOptions options, std::function block) const; /** * @brief Calls `-[NSTextLayoutManager enumerateTextSegmentsInRange:type:options:usingBlock:]`. - * @details Enumerates text segments of a specific type and in the text range you provide. A text segment is both logically and visually contiguous portion of the text content inside a line fragment. It can be defined with a single text range. The segments are enumerated visually from left to right. Returning 'false' from block breaks out of the enumeration. - Parameters: - textRange: The range to enumerate segments in. - type: The segment type. - options: Options controlling segment behavior. - block: A block called for each segment. Return 'false' to stop. * @param text_range Argument converted to the Objective-C parameter of the same role. * @param type Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. @@ -109,26 +98,22 @@ namespace cocoon void enumerate_text_segments_in_range(const TextRange& text_range, TextLayoutManagerSegmentType type, TextLayoutManagerSegmentOptions options, std::function block) const; /** * @brief Calls `-[NSTextLayoutManager invalidateLayoutForRange:]`. - * @details Invalidates layout information for the specified text range. - Parameters: - range: The text range to invalidate. * @param range Argument converted to the Objective-C parameter of the same role. */ void invalidate_layout_for_range(const TextRange& range) const; /** * @brief Calls `-[NSTextLayoutManager invalidateRenderingAttributesForTextRange:]`. - * @details Invalidates the rendering attributes in the specified text range. Enumerating rendering attributes will skip the invalidated range. - Parameters: - textRange: The range to invalidate. * @param text_range Argument converted to the Objective-C parameter of the same role. */ void invalidate_rendering_attributes_for_text_range(const TextRange& text_range) const; /** * @brief Calls `-[NSTextLayoutManager removeRenderingAttribute:forTextRange:]`. - * @details Removes the rendering attribute from the specified text range. This is a convenience over ''setRenderingAttributes:forTextRange:''. - Parameters: - renderingAttribute: The \ attribute to remove. - textRange: The range to remove the attribute from. * @param rendering_attribute Argument converted to the Objective-C parameter of the same role. * @param text_range Argument converted to the Objective-C parameter of the same role. */ void remove_rendering_attribute(const std::string& rendering_attribute, const TextRange& text_range) const; /** * @brief Calls `-[NSTextLayoutManager renderingAttributesForLink:atLocation:]`. - * @details Returns a dictionary of rendering attributes for rendering a link. Just as other rendering attributes, specifying \ removes the attribute from the final attributes used for rendering. It has priority over the general rendering attributes. - Parameters: - link: The link object. - location: The document location of the link. - Returns: A dictionary of rendering attributes. * @param link Argument converted to the Objective-C parameter of the same role. * @param location Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -136,174 +121,148 @@ namespace cocoon std::map rendering_attributes_for_link(const Object& link, const Object& location) const; /** * @brief Calls `-[NSTextLayoutManager replaceContentsInRange:withAttributedString:]`. - * @details Replaces content at the location you specify with an attributed string you provide. - Parameters: - range: The range of the content to replace. - attributedString: An attributed string to replace the content at 'range'. * @param range Argument converted to the Objective-C parameter of the same role. * @param attributed_string Argument converted to the Objective-C parameter of the same role. */ void replace_contents_in_range(const TextRange& range, const AttributedString& attributed_string) const; /** * @brief Calls `-[NSTextLayoutManager replaceContentsInRange:withTextElements:]`. - * @details Replaces content at the location you specify with the text elements you provide. - Parameters: - range: The range of the content to replace. - textElements: An array of text elements. * @param range Argument converted to the Objective-C parameter of the same role. * @param text_elements Argument converted to the Objective-C parameter of the same role. */ void replace_contents_in_range(const TextRange& range, const std::vector& text_elements) const; /** * @brief Calls `-[NSTextLayoutManager replaceTextContentManager:]`. - * @details Replaces the current text content manager with a new one you provide. This method should be used in order to replace an ''NSTextContentManager'' with a new one, leaving all related objects intact. This method makes sure the ''NSTextLayoutManager'' doesn't get deallocated while migrating to the new manager. - Parameters: - textContentManager: The new content manager. * @param text_content_manager Argument converted to the Objective-C parameter of the same role. */ void replace_text_content_manager(const TextContentManager& text_content_manager) const; /** * @brief Calls `-[NSTextLayoutManager setRenderingAttributes:forTextRange:]`. - * @details Sets the rendering attributes for the range you specify. - Parameters: - renderingAttributes: The attributes to set. - textRange: The range to apply attributes to. * @param rendering_attributes Argument converted to the Objective-C parameter of the same role. * @param text_range Argument converted to the Objective-C parameter of the same role. */ void set_rendering_attributes(const std::map& rendering_attributes, const TextRange& text_range) const; /** * @brief Calls `-[NSTextLayoutManager textLayoutFragmentForLocation:]`. - * @details Returns the text layout fragment from the document at the specified location. - Parameters: - location: A document location. - Returns: The layout fragment containing the location, or 'nil'. * @param location Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ TextLayoutFragment text_layout_fragment_for_location(const Object& location) const; /** * @brief Calls `-[NSTextLayoutManager textLayoutFragmentForPosition:]`. - * @details Returns the text layout fragment at the position you specify in the text container. - Parameters: - position: A \ in the text container coordinate system. - Returns: The layout fragment containing the position, or 'nil'. * @param position Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ TextLayoutFragment text_layout_fragment_for_position(const Point& position) const; /** * @brief Returns the `layoutQueue` property of `NSTextLayoutManager`. - * @details The queue that the framework dispatches layout operations on. If non-nil, it performs layout in the specified queue until 'estimatedUsageBounds' is 'false'. * @return The converted Objective-C result. */ OperationQueue layout_queue() const; /** * @brief Sets the `layoutQueue` property of `NSTextLayoutManager`. - * @details The queue that the framework dispatches layout operations on. If non-nil, it performs layout in the specified queue until 'estimatedUsageBounds' is 'false'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_layout_queue(const OperationQueue& value) const; /** * @brief Returns the `limitsLayoutForSuspiciousContents` property of `NSTextLayoutManager`. - * @details A Boolean value that controls internal security analysis for malicious inputs and activates defensive behaviors. By enabling this functionality, it's possible certain text such as a very long paragraph might result in unexpected layout. The default value is 'false'. * @return The converted Objective-C result. */ bool limits_layout_for_suspicious_contents() const; /** * @brief Sets the `limitsLayoutForSuspiciousContents` property of `NSTextLayoutManager`. - * @details A Boolean value that controls internal security analysis for malicious inputs and activates defensive behaviors. By enabling this functionality, it's possible certain text such as a very long paragraph might result in unexpected layout. The default value is 'false'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_limits_layout_for_suspicious_contents(bool value) const; /** * @brief Returns the `linkRenderingAttributes` property of `NSTextLayoutManager`. - * @details Returns the default set of attributes for rendering 'NSLinkAttributeName'. The base ''NSTextLayoutManager'' class returns with ''NSUnderlineStyle/single'' for \ in Swift or ''NSUnderlineStyleAttributeName'' in Objective-C, and the platform link color for \ in Swift or ''NSForegroundColorAttributeName'' in Objective-C. The platform color for macOS is 'linkColor'. Other platforms use 'blueColor'. * @return The converted Objective-C result. */ static std::map link_rendering_attributes(); /** * @brief Returns the `renderingAttributesValidator` property of `NSTextLayoutManager`. - * @details A callback block that the framework invokes whenever the text layout manager needs to validate the rendering attributes for the range. The validator should use ''setRenderingAttributes:forTextRange:'' to fill the rendering attributes appropriate for the range inside 'textLayoutFragment'. * @return The converted Objective-C result. */ std::function rendering_attributes_validator() const; /** * @brief Sets the `renderingAttributesValidator` property of `NSTextLayoutManager`. - * @details A callback block that the framework invokes whenever the text layout manager needs to validate the rendering attributes for the range. The validator should use ''setRenderingAttributes:forTextRange:'' to fill the rendering attributes appropriate for the range inside 'textLayoutFragment'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_rendering_attributes_validator(std::function value) const; /** * @brief Returns the `resolvesNaturalAlignmentWithBaseWritingDirection` property of `NSTextLayoutManager`. - * @details Specifies the behavior for resolving ''NSTextAlignment/natural'' to the visual alignment. When set to 'true', the resolved visual alignment is determined by the resolved base writing direction; otherwise, it is using the user’s preferred language. The default value is 'true'. + * @details Specifies the behavior for resolving ''NSTextAlignment.natural'' to the visual alignment. When set to ''true'', the resolved visual alignment is determined by the resolved base writing direction; otherwise, it is using the user’s preferred language. The default value is ''true''. * @return The converted Objective-C result. */ bool resolves_natural_alignment_with_base_writing_direction() const; /** * @brief Sets the `resolvesNaturalAlignmentWithBaseWritingDirection` property of `NSTextLayoutManager`. - * @details Specifies the behavior for resolving ''NSTextAlignment/natural'' to the visual alignment. When set to 'true', the resolved visual alignment is determined by the resolved base writing direction; otherwise, it is using the user’s preferred language. The default value is 'true'. + * @details Specifies the behavior for resolving ''NSTextAlignment.natural'' to the visual alignment. When set to ''true'', the resolved visual alignment is determined by the resolved base writing direction; otherwise, it is using the user’s preferred language. The default value is ''true''. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_resolves_natural_alignment_with_base_writing_direction(bool value) const; /** * @brief Returns the `textContainer` property of `NSTextLayoutManager`. - * @details The text container object that provides geometric information for the layout destination. If 'isSimpleRectangularTextContainer' is 'false', ''NSTextLayoutManager'' always fills from the top instead of allowing non-contiguous layout support. * @return The converted Objective-C result. */ TextContainer text_container() const; /** * @brief Sets the `textContainer` property of `NSTextLayoutManager`. - * @details The text container object that provides geometric information for the layout destination. If 'isSimpleRectangularTextContainer' is 'false', ''NSTextLayoutManager'' always fills from the top instead of allowing non-contiguous layout support. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_container(const TextContainer& value) const; /** * @brief Returns the `textContentManager` property of `NSTextLayoutManager`. - * @details Returns the text content manager associated with this text layout manager. * @return The converted Objective-C result. */ TextContentManager text_content_manager() const; /** * @brief Returns the `textSelectionNavigation` property of `NSTextLayoutManager`. - * @details Returns a text selection navigation configured to have the text layout manager as its data source. * @return The converted Objective-C result. */ TextSelectionNavigation text_selection_navigation() const; /** * @brief Sets the `textSelectionNavigation` property of `NSTextLayoutManager`. - * @details Returns a text selection navigation configured to have the text layout manager as its data source. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_selection_navigation(const TextSelectionNavigation& value) const; /** * @brief Returns the `textSelections` property of `NSTextLayoutManager`. - * @details An array of text selections associated by the text layout manager. Each ''NSTextSelection'' represents an insertion point. The selection state is shared among all view ports connected to the text layout manager via text containers. * @return The converted Objective-C result. */ std::vector text_selections() const; /** * @brief Sets the `textSelections` property of `NSTextLayoutManager`. - * @details An array of text selections associated by the text layout manager. Each ''NSTextSelection'' represents an insertion point. The selection state is shared among all view ports connected to the text layout manager via text containers. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_selections(const std::vector& value) const; /** * @brief Returns the `textViewportLayoutController` property of `NSTextLayoutManager`. - * @details Returns the text viewport layout controller associated with the text layout manager's text container. * @return The converted Objective-C result. */ TextViewportLayoutController text_viewport_layout_controller() const; /** * @brief Returns the `usageBoundsForTextContainer` property of `NSTextLayoutManager`. - * @details Returns the usage bounds for the text container. KVO-compliant. Views can observe this property in order to trigger a resize operation. For example, 'UIView'/'NSView' should call 'setNeedsUpdateConstraints()' when the usage bounds changes. * @return The converted Objective-C result. */ Rect usage_bounds_for_text_container() const; /** * @brief Returns the `usesFontLeading` property of `NSTextLayoutManager`. - * @details A Boolean value that controls whether the framework uses the leading information specified by the font when laying out text. If set to 'true', uses the leading as specified by the font. However, this isn't appropriate for most UI text. The default value is 'true'. * @return The converted Objective-C result. */ bool uses_font_leading() const; /** * @brief Sets the `usesFontLeading` property of `NSTextLayoutManager`. - * @details A Boolean value that controls whether the framework uses the leading information specified by the font when laying out text. If set to 'true', uses the leading as specified by the font. However, this isn't appropriate for most UI text. The default value is 'true'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_uses_font_leading(bool value) const; /** * @brief Returns the `usesHyphenation` property of `NSTextLayoutManager`. - * @details A Boolean value that controls whether the text layout manager attempts to hyphenate when wrapping lines. May be overridden on a per-paragraph basis by the 'NSParagraphStyle''s 'usesDefaultHyphenation'. The receiver makes the best effort to decide the exact logic including the hyphenation factor based on the context. The default value is 'false'. Can be overridden by the preference key '"NSUsesDefaultHyphenation"'. * @return The converted Objective-C result. */ bool uses_hyphenation() const; /** * @brief Sets the `usesHyphenation` property of `NSTextLayoutManager`. - * @details A Boolean value that controls whether the text layout manager attempts to hyphenate when wrapping lines. May be overridden on a per-paragraph basis by the 'NSParagraphStyle''s 'usesDefaultHyphenation'. The receiver makes the best effort to decide the exact logic including the hyphenation factor based on the context. The default value is 'false'. Can be overridden by the preference key '"NSUsesDefaultHyphenation"'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_uses_hyphenation(bool value) const; @@ -322,21 +281,6 @@ namespace cocoon { return Signal(Object, Object, std::map)>(handle(), "rendering_attributes_for_link_at_location_default_attributes"); } -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `cache_text_attachment_view_provider_for_text_attachment`; connect a callback with `cache_text_attachment_view_provider_for_text_attachment().connect(...)`. - Signal cache_text_attachment_view_provider_for_text_attachment() const - { - return Signal(handle(), "cache_text_attachment_view_provider_for_text_attachment"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `retrieve_cached_text_attachment_view_provider_for_text_attachment`; connect a callback with `retrieve_cached_text_attachment_view_provider_for_text_attachment().connect(...)`. - Signal retrieve_cached_text_attachment_view_provider_for_text_attachment() const - { - return Signal(handle(), "retrieve_cached_text_attachment_view_provider_for_text_attachment"); - } -#endif protected: static void install_delegate_delegate_(void* native); diff --git a/include/generated/text_line_fragment.h b/include/generated/text_line_fragment.h index a3de2cc0..f7ede587 100644 --- a/include/generated/text_line_fragment.h +++ b/include/generated/text_line_fragment.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextLineFragment` (AppKit). - * @details A class that represents a line fragment as a single textual layout and rendering unit inside a text layout fragment. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,53 +46,45 @@ namespace cocoon explicit TextLineFragment(Adopt adopt); /** * @brief Calls `-[NSTextLineFragment characterIndexForPoint:]`. - * @details Returns the character index for the point inside the line fragment coordinate system. - Parameters: - point: A \ in the line fragment coordinate system. - Returns: The character index nearest to the point. * @param point Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::int64_t character_index_for_point(const Point& point) const; /** * @brief Calls `-[NSTextLineFragment drawAtPoint:inContext:]`. - * @details Renders the line fragment contents at the specified point. The origin can be specified as '(CGRectGetMinX(typographicBounds), CGRectGetMinY(typographicBounds))' relative to the parent layout fragment coordinate system. - Parameters: - point: The origin as a \. - context: The graphics context to draw into. * @param point Argument converted to the Objective-C parameter of the same role. * @param context Argument converted to the Objective-C parameter of the same role. */ void draw_at_point(const Point& point, const CGContext& context) const; /** * @brief Calls `-[NSTextLineFragment fractionOfDistanceThroughGlyphForPoint:]`. - * @details Returns the fraction of the distance through the glyph for the point. The fraction of distance is from the upstream edge. - Parameters: - point: A \ in the line fragment coordinate system. - Returns: A value between 0.0 and 1.0 indicating the fraction through the glyph. * @param point Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double fraction_of_distance_through_glyph_for_point(const Point& point) const; /** * @brief Calls `-[NSTextLineFragment locationForCharacterAtIndex:]`. - * @details Returns the location of the character at the specified index. The location is on the upstream edge of the glyph, in the coordinate system relative to the line fragment origin. - Parameters: - index: The character index within this line fragment. - Returns: A \ on the upstream edge of the glyph, in the coordinate system relative to the line fragment origin. * @param index Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Point location_for_character_at_index(std::int64_t index) const; /** * @brief Returns the `attributedString` property of `NSTextLineFragment`. - * @details The source attributed string. * @return The converted Objective-C result. */ AttributedString attributed_string() const; /** * @brief Returns the `characterRange` property of `NSTextLineFragment`. - * @details The string range for the source attributed string corresponding to this line fragment. * @return The converted Objective-C result. */ Range character_range() const; /** * @brief Returns the `glyphOrigin` property of `NSTextLineFragment`. - * @details The rendering origin for the leftmost glyph in the line fragment coordinate system. * @return The converted Objective-C result. */ Point glyph_origin() const; /** * @brief Returns the `typographicBounds` property of `NSTextLineFragment`. - * @details The typographic bounds specifying the dimensions of the line fragment for laying out line fragments to each other. The origin value is offset from the beginning of the line fragment group belonging to the parent layout fragment. * @return The converted Objective-C result. */ Rect typographic_bounds() const; diff --git a/include/generated/text_list.h b/include/generated/text_list.h index b0c69768..6a5060f3 100644 --- a/include/generated/text_list.h +++ b/include/generated/text_list.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSTextList` (AppKit). - * @details A section of text that forms a single list. The visible elements of the list, including list markers, appear in the text as they do for lists created by hand. The list object, however, allows the list to be recognized as such by the text system. This enables automatic creation of markers and spacing. Text lists are used in HTML import and export. Text lists appear as attributes on paragraphs, as part of the paragraph style. An ''NSParagraphStyle'' may have an array of text lists, representing the nested lists containing the paragraph, in order from outermost to innermost. For example, if list1 contains four paragraphs, the middle two of which are also in the inner list2, then the text lists array for the first and fourth paragraphs is (list1), while the text lists array for the second and third paragraphs is (list1, list2). The methods implementing this are ''NSParagraphStyle/textLists'' on ''NSParagraphStyle'', and ''NSMutableParagraphStyle/textLists'' on ''NSMutableParagraphStyle''. In addition, \ has convenience methods for lists, such as \, which determines the range covered by a list, and \, which determines the ordinal position within a list of a particular item. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -46,44 +45,37 @@ namespace cocoon explicit TextList(Adopt adopt); /** * @brief Calls `-[NSTextList markerForItemNumber:]`. - * @details Returns the computed value for a specific ordinal position in the list. - Parameters: - itemNumber: The ordinal position in the list whose computed marker value is desired. The receiver ignores this parameter if 'itemNumber' is less than 1 or ''isOrdered'' is 'false'. - Returns: The computed marker value for 'itemNumber'. * @param item_number Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string marker_for_item_number(std::int64_t item_number) const; /** * @brief Returns the `includesTextListMarkers` property of `NSTextList`. - * @details A Boolean value that indicates whether TextKit includes text list markers in the contents. The default value is 'false'. * @return The converted Objective-C result. */ static bool includes_text_list_markers(); /** * @brief Returns the `listOptions` property of `NSTextList`. - * @details The list options mask value of the receiver. * @return The converted Objective-C result. */ TextListOptions list_options() const; /** * @brief Returns the `markerFormat` property of `NSTextList`. - * @details The marker format string used by the receiver. \#\# See Also - ''NSTextList/init(markerFormat:options:)'' * @return The converted Objective-C result. */ std::string marker_format() const; /** * @brief Returns the `ordered` property of `NSTextList`. - * @details A Boolean value that indicates whether the list is ordered. * @return The converted Objective-C result. */ bool is_ordered() const; /** * @brief Returns the `startingItemNumber` property of `NSTextList`. - * @details The starting item number for the text list. The default value is '1'. This value will be used only for ordered lists, and ignored in other cases. * @return The converted Objective-C result. */ std::int64_t starting_item_number() const; /** * @brief Sets the `startingItemNumber` property of `NSTextList`. - * @details The starting item number for the text list. The default value is '1'. This value will be used only for ordered lists, and ignored in other cases. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_starting_item_number(std::int64_t value) const; diff --git a/include/generated/text_list_element.h b/include/generated/text_list_element.h index 9e9807cd..494602db 100644 --- a/include/generated/text_list_element.h +++ b/include/generated/text_list_element.h @@ -44,37 +44,31 @@ namespace cocoon using TextParagraph::attributed_string; /** * @brief Returns the `attributedString` property of `NSTextListElement`. - * @details An attributed string that represents the string the framework displays for this element taking into account markers and the indentation level of the list element. Derived from ''contents'' and ''textList'' configured with the text list element's position inside the tree. Overrides 'NSTextParagraph.attributedString'. * @return The converted Objective-C result. */ AttributedString attributed_string() const; /** * @brief Returns the `childElements` property of `NSTextListElement`. - * @details An array that contains child text elements. * @return The converted Objective-C result. */ std::vector child_elements() const; /** * @brief Returns the `contents` property of `NSTextListElement`. - * @details The text list element contents without markers and formatting. * @return The converted Objective-C result. */ AttributedString contents() const; /** * @brief Returns the `markerAttributes` property of `NSTextListElement`. - * @details A dictionary of attributed string keys and values that represent the list's marker attributes. * @return The converted Objective-C result. */ std::map marker_attributes() const; /** * @brief Returns the `parentElement` property of `NSTextListElement`. - * @details A text list element that refers to the enclosing text list element. * @return The converted Objective-C result. */ TextListElement parent_element() const; /** * @brief Returns the `textList` property of `NSTextListElement`. - * @details The value that represents the text list. * @return The converted Objective-C result. */ TextList text_list() const; diff --git a/include/generated/text_paragraph.h b/include/generated/text_paragraph.h index 0f44017a..7d900ff7 100644 --- a/include/generated/text_paragraph.h +++ b/include/generated/text_paragraph.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextParagraph` (AppKit). - * @details A class that represents a single paragraph backed by an attributed string as the contents. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref TextElement. * @@ -38,19 +37,16 @@ namespace cocoon explicit TextParagraph(Adopt adopt); /** * @brief Returns the `attributedString` property of `NSTextParagraph`. - * @details The source attributed string. * @return The converted Objective-C result. */ AttributedString attributed_string() const; /** * @brief Returns the `paragraphContentRange` property of `NSTextParagraph`. - * @details The range of the paragraph's content within the document. The paragraph's content is the text up to but not including the paragraph separator. Together with ''paragraphSeparatorRange'', this range covers the entire ''NSTextElement/elementRange''. * @return The converted Objective-C result. */ TextRange paragraph_content_range() const; /** * @brief Returns the `paragraphSeparatorRange` property of `NSTextParagraph`. - * @details The range of the paragraph separator within the document. Together with ''paragraphContentRange'', this range covers the entire ''NSTextElement/elementRange''. * @return The converted Objective-C result. */ TextRange paragraph_separator_range() const; diff --git a/include/generated/text_selection.h b/include/generated/text_selection.h index f8d2c5de..89b0f7c2 100644 --- a/include/generated/text_selection.h +++ b/include/generated/text_selection.h @@ -49,80 +49,67 @@ namespace cocoon explicit TextSelection(Adopt adopt); /** * @brief Calls `-[NSTextSelection textSelectionWithTextRanges:]`. - * @details Returns a copy of this selection, replacing the text ranges with the ones you provide. All other attributes remain the same. - Parameters: - textRanges: The new text ranges for the returned selection. - Returns: A new ''NSTextSelection'' with the updated ranges. * @param text_ranges Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ TextSelection text_selection_with_text_ranges(const std::vector& text_ranges) const; /** * @brief Returns the `affinity` property of `NSTextSelection`. - * @details Either upstream or downstream selection. 'NSTextSelectionAffinityDownstream' by default. For a 0-length selection, it describes the visual location of the text cursor between the head of line containing the selection location (downstream) or tail of the previous line (upstream). For a selection with contents, it describes the logical direction of the non-anchored edge of the selection. * @return The converted Objective-C result. */ TextSelectionAffinity affinity() const; /** * @brief Returns the `anchorPositionOffset` property of `NSTextSelection`. - * @details The anchor position offset from the beginning of a line fragment in visual order. That is, from the left for a horizontal line fragment and from the top for a vertical. Navigating between lines uses this point when the current line fragment associated with the selection is shorter than the next line visited. The default value is '0.0'. * @return The converted Objective-C result. */ double anchor_position_offset() const; /** * @brief Sets the `anchorPositionOffset` property of `NSTextSelection`. - * @details The anchor position offset from the beginning of a line fragment in visual order. That is, from the left for a horizontal line fragment and from the top for a vertical. Navigating between lines uses this point when the current line fragment associated with the selection is shorter than the next line visited. The default value is '0.0'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_anchor_position_offset(double value) const; /** * @brief Returns the `granularity` property of `NSTextSelection`. - * @details The granularity of the selection. 'NSTextSelectionGranularityCharacter' by default. Extending operations should modify the selection by the granularity. * @return The converted Objective-C result. */ TextSelectionGranularity granularity() const; /** * @brief Returns the `logical` property of `NSTextSelection`. - * @details A Boolean value indicating whether the selection should be interpreted as logical or visual. * @return The converted Objective-C result. */ bool is_logical() const; /** * @brief Sets the `logical` property of `NSTextSelection`. - * @details A Boolean value indicating whether the selection should be interpreted as logical or visual. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_logical(bool value) const; /** * @brief Returns the `secondarySelectionLocation` property of `NSTextSelection`. - * @details The secondary character location when the user taps or clicks at a directional boundary. Setting a non-nil location has a side effect of making ''logical'' 'false'. * @return The converted Objective-C result. */ Object secondary_selection_location() const; /** * @brief Sets the `secondarySelectionLocation` property of `NSTextSelection`. - * @details The secondary character location when the user taps or clicks at a directional boundary. Setting a non-nil location has a side effect of making ''logical'' 'false'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_secondary_selection_location(const Object& value) const; /** * @brief Returns the `textRanges` property of `NSTextSelection`. - * @details An array of disjoint logical ranges in the selection. The array must be logically ordered. When editing, all ranges in a text selection constitute a single insertion point. * @return The converted Objective-C result. */ std::vector text_ranges() const; /** * @brief Returns the `transient` property of `NSTextSelection`. - * @details A Boolean value indicating whether this is a transient text selection during drag handling. * @return The converted Objective-C result. */ bool is_transient() const; /** * @brief Returns the `typingAttributes` property of `NSTextSelection`. - * @details The template attributes used for characters replacing the contents of this selection. * @return The converted Objective-C result. */ std::map typing_attributes() const; /** * @brief Sets the `typingAttributes` property of `NSTextSelection`. - * @details The template attributes used for characters replacing the contents of this selection. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_typing_attributes(const std::map& value) const; diff --git a/include/generated/text_selection_manager.h b/include/generated/text_selection_manager.h deleted file mode 100644 index fb23ec3b..00000000 --- a/include/generated/text_selection_manager.h +++ /dev/null @@ -1,185 +0,0 @@ -#pragma once - -#include "generated/availability.h" - -#ifdef COCOON_MACOS_27 -#include "generated/enums.h" -#include "generated/structs.h" -#include "object.h" -#include "types.h" - -namespace cocoon -{ - class DraggingSession; - class GestureRecognizer; - class TextRange; - - /** - * @brief C++ handle for the Objective-C class `NSTextSelectionManager` (AppKit). - * @details An object that coordinates text selection behavior for custom text views. ''NSTextSelectionManager'' provides a centralized way to manage text selection interactions using a set of gesture recognizers. For keyboard-based selection, integrate ''NSTextSelectionNavigation'' with your view. The selection manager works with a delegate to update and respond to selection changes, and with a data source to query the text layout system. - * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. - * - * @par Example - * @code - * #include - * - * cocoon::TextSelectionManager text_selection_manager; - * text_selection_manager.set_text_selection_mode(cocoon::TextSelectionMode::Editable); - * text_selection_manager.selection_manager_will_begin_selection().connect([](auto&&...) {}); - * @endcode - * - * @par Common tasks - * Snippets built from this class's own members (values are placeholders). - * @code - * cocoon::TextSelectionManager text_selection_manager{}; - * text_selection_manager.set_text_selection_mode(cocoon::TextSelectionMode::Editable); - * auto text_selection_mode = text_selection_manager.text_selection_mode(); - * text_selection_manager.selection_manager_will_begin_selection().connect([]() {}); - * text_selection_manager.selection_manager_did_end_selection().connect([]() {}); - * @endcode - * @see https://developer.apple.com/documentation/appkit/nstextselectionmanager - */ - class TextSelectionManager : public Object - { - public: - /// @brief Creates a new `NSTextSelectionManager` instance and returns a handle to it. - explicit TextSelectionManager(); - /// @brief Creates a null handle that refers to no native object. - TextSelectionManager(std::nullptr_t); - /// @brief Wraps an existing retained native object without creating a new one. - explicit TextSelectionManager(Adopt adopt); -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `gesturesForFailureRequirements` property of `NSTextSelectionManager`. - * @details The gesture recognizers managed by the selection manager. Other gesture recognizers in the view hierarchy can declare dependencies on these gestures using 'requireGestureRecognizerToFail:' to ensure proper gesture recognition precedence. - * @return The converted Objective-C result. - */ - std::vector gestures_for_failure_requirements() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `textSelectionMode` property of `NSTextSelectionManager`. - * @details The interaction mode for text selection. Determines whether text is editable, selectable only, or non-interactive. The default value is 'NSTextSelectionModeEditable'. - * @return The converted Objective-C result. - */ - TextSelectionMode text_selection_mode() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `textSelectionMode` property of `NSTextSelectionManager`. - * @details The interaction mode for text selection. Determines whether text is editable, selectable only, or non-interactive. The default value is 'NSTextSelectionModeEditable'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_text_selection_mode(TextSelectionMode value) const; -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `selection_manager_should_begin_selection_at_point`; connect a callback with `selection_manager_should_begin_selection_at_point().connect(...)`. - Signal selection_manager_should_begin_selection_at_point() const - { - return Signal(handle(), "selection_manager_should_begin_selection_at_point"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `selection_manager_will_begin_selection`; connect a callback with `selection_manager_will_begin_selection().connect(...)`. - Signal selection_manager_will_begin_selection() const - { - return Signal(handle(), "selection_manager_will_begin_selection"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `selection_manager_did_end_selection`; connect a callback with `selection_manager_did_end_selection().connect(...)`. - Signal selection_manager_did_end_selection() const - { - return Signal(handle(), "selection_manager_did_end_selection"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `selection_manager_location_of_text_container_at_point`; connect a callback with `selection_manager_location_of_text_container_at_point().connect(...)`. - Signal selection_manager_location_of_text_container_at_point() const - { - return Signal(handle(), "selection_manager_location_of_text_container_at_point"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `selection_manager_frame_of_text_container_at_point`; connect a callback with `selection_manager_frame_of_text_container_at_point().connect(...)`. - Signal selection_manager_frame_of_text_container_at_point() const - { - return Signal(handle(), "selection_manager_frame_of_text_container_at_point"); - } -#endif - -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `selection_manager_make_dragging_session_with_gesture`; connect a callback with `selection_manager_make_dragging_session_with_gesture().connect(...)`. - Signal selection_manager_make_dragging_session_with_gesture() const - { - return Signal(handle(), "selection_manager_make_dragging_session_with_gesture"); - } -#endif - - /// @brief Signal for the delegate/data-source method behind `enumerate_substrings_from_location_options_using_block`; connect a callback with `enumerate_substrings_from_location_options_using_block().connect(...)`. - Signal)> enumerate_substrings_from_location_options_using_block() const - { - return Signal)>(handle(), "enumerate_substrings_from_location_options_using_block"); - } - /// @brief Signal for the delegate/data-source method behind `text_range_for_selection_granularity_enclosing_location`; connect a callback with `text_range_for_selection_granularity_enclosing_location().connect(...)`. - Signal text_range_for_selection_granularity_enclosing_location() const - { - return Signal(handle(), "text_range_for_selection_granularity_enclosing_location"); - } - /// @brief Signal for the delegate/data-source method behind `location_from_location_with_offset`; connect a callback with `location_from_location_with_offset().connect(...)`. - Signal location_from_location_with_offset() const - { - return Signal(handle(), "location_from_location_with_offset"); - } - /// @brief Signal for the delegate/data-source method behind `offset_from_location_to_location`; connect a callback with `offset_from_location_to_location().connect(...)`. - Signal offset_from_location_to_location() const - { - return Signal(handle(), "offset_from_location_to_location"); - } - /// @brief Signal for the delegate/data-source method behind `base_writing_direction_at_location`; connect a callback with `base_writing_direction_at_location().connect(...)`. - Signal base_writing_direction_at_location() const - { - return Signal(handle(), "base_writing_direction_at_location"); - } - /// @brief Signal for the delegate/data-source method behind `enumerate_caret_offsets_in_line_fragment_at_location_using_block`; connect a callback with `enumerate_caret_offsets_in_line_fragment_at_location_using_block().connect(...)`. - Signal)> enumerate_caret_offsets_in_line_fragment_at_location_using_block() const - { - return Signal)>(handle(), "enumerate_caret_offsets_in_line_fragment_at_location_using_block"); - } - /// @brief Signal for the delegate/data-source method behind `line_fragment_range_for_point_in_container_at_location`; connect a callback with `line_fragment_range_for_point_in_container_at_location().connect(...)`. - Signal line_fragment_range_for_point_in_container_at_location() const - { - return Signal(handle(), "line_fragment_range_for_point_in_container_at_location"); - } - /// @brief Signal for the delegate/data-source method behind `enumerate_container_boundaries_from_location_reverse_using_block`; connect a callback with `enumerate_container_boundaries_from_location_reverse_using_block().connect(...)`. - Signal)> enumerate_container_boundaries_from_location_reverse_using_block() const - { - return Signal)>(handle(), "enumerate_container_boundaries_from_location_reverse_using_block"); - } - /// @brief Signal for the delegate/data-source method behind `text_layout_orientation_at_location`; connect a callback with `text_layout_orientation_at_location().connect(...)`. - Signal text_layout_orientation_at_location() const - { - return Signal(handle(), "text_layout_orientation_at_location"); - } -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `convert_interaction_point_to_container_at_location`; connect a callback with `convert_interaction_point_to_container_at_location().connect(...)`. - Signal convert_interaction_point_to_container_at_location() const - { - return Signal(handle(), "convert_interaction_point_to_container_at_location"); - } -#endif - - protected: - static void install_delegate_delegate_(void* native); - static void install_text_selection_data_source_delegate_(void* native); - }; -} - -#endif diff --git a/include/generated/text_selection_navigation.h b/include/generated/text_selection_navigation.h index ab5c68ff..d8e52374 100644 --- a/include/generated/text_selection_navigation.h +++ b/include/generated/text_selection_navigation.h @@ -49,7 +49,6 @@ namespace cocoon explicit TextSelectionNavigation(Adopt adopt); /** * @brief Calls `-[NSTextSelectionNavigation deletionRangesForTextSelection:direction:destination:allowsDecomposition:]`. - * @details Returns the ranges that should be deleted based on the text selection and movement arguments. The selection after deletion should contain a 0-length range starting at the location of the first range returned. 'destination' is ignored when 'textSelection' has a non-empty selection. 'allowsDecomposition' only applies to 'NSTextSelectionNavigationDirectionBackward' and 'NSTextSelectionNavigationDestinationCharacter' with a 0-length selection. - Parameters: - textSelection: The current text selection. - direction: The deletion direction. - destination: The deletion destination granularity. - allowsDecomposition: Whether to allow character decomposition during backward deletion. - Returns: An array of ranges to delete. * @param text_selection Argument converted to the Objective-C parameter of the same role. * @param direction Argument converted to the Objective-C parameter of the same role. * @param destination Argument converted to the Objective-C parameter of the same role. @@ -59,7 +58,6 @@ namespace cocoon std::vector deletion_ranges_for_text_selection(const TextSelection& text_selection, TextSelectionNavigationDirection direction, TextSelectionNavigationDestination destination, bool allows_decomposition) const; /** * @brief Calls `-[NSTextSelectionNavigation destinationSelectionForTextSelection:direction:destination:extending:confined:]`. - * @details Returns a new selection that results from applying the navigation operations you specify to the text selection you provide. Returns 'nil' when the requested operation does not produce any logically valid result. - Parameters: - textSelection: The starting text selection. - direction: The navigation direction. - destination: The navigation destination granularity. - extending: Whether to extend the selection. - confined: If 'true', confines movement to the text element the selection already lies within. - Returns: The resulting text selection, or 'nil' if the operation is invalid. * @param text_selection Argument converted to the Objective-C parameter of the same role. * @param direction Argument converted to the Objective-C parameter of the same role. * @param destination Argument converted to the Objective-C parameter of the same role. @@ -70,12 +68,10 @@ namespace cocoon TextSelection destination_selection_for_text_selection(const TextSelection& text_selection, TextSelectionNavigationDirection direction, TextSelectionNavigationDestination destination, bool extending, bool confined) const; /** * @brief Calls `-[NSTextSelectionNavigation flushLayoutCache]`. - * @details Flushes cached layout information. Should be called whenever the document contents change. */ void flush_layout_cache() const; /** * @brief Calls `-[NSTextSelectionNavigation resolvedInsertionLocationForTextSelection:writingDirection:]`. - * @details Returns the resolved location for inserting the next input when the selection is at a bidirectional boundary. Returns 'nil' if 'textSelection' has 'isLogical == YES' or 'secondarySelectionLocation == nil'. - Parameters: - textSelection: The current text selection. - writingDirection: The active input writing direction. - Returns: The resolved insertion location, or 'nil'. * @param text_selection Argument converted to the Objective-C parameter of the same role. * @param writing_direction Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -83,7 +79,6 @@ namespace cocoon Object resolved_insertion_location_for_text_selection(const TextSelection& text_selection, TextSelectionNavigationWritingDirection writing_direction) const; /** * @brief Calls `-[NSTextSelectionNavigation textSelectionForSelectionGranularity:enclosingPoint:inContainerAtLocation:]`. - * @details Returns a text selection expanded to the nearest boundaries for the specified granularity that contains the given point. The returned selection will have 'granularity' set to 'selectionGranularity'. - Parameters: - selectionGranularity: The granularity to expand to. - point: The point in the container coordinate system. - location: The location identifying the text container. - Returns: The expanded text selection, or 'nil'. * @param selection_granularity Argument converted to the Objective-C parameter of the same role. * @param point Argument converted to the Objective-C parameter of the same role. * @param location Argument converted to the Objective-C parameter of the same role. @@ -92,7 +87,6 @@ namespace cocoon TextSelection text_selection_for_selection_granularity(TextSelectionGranularity selection_granularity, const Point& point, const Object& location) const; /** * @brief Calls `-[NSTextSelectionNavigation textSelectionForSelectionGranularity:enclosingTextSelection:]`. - * @details Returns a text selection expanded to the nearest boundaries for the specified granularity enclosing the given selection. The returned selection will have 'granularity' set to 'selectionGranularity'. - Parameters: - selectionGranularity: The granularity to expand to. - textSelection: The selection to expand. - Returns: The expanded text selection. * @param selection_granularity Argument converted to the Objective-C parameter of the same role. * @param text_selection Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -100,7 +94,6 @@ namespace cocoon TextSelection text_selection_for_selection_granularity(TextSelectionGranularity selection_granularity, const TextSelection& text_selection) const; /** * @brief Calls `-[NSTextSelectionNavigation textSelectionsInteractingAtPoint:inContainerAtLocation:anchors:modifiers:selecting:bounds:]`. - * @details Returns an array of text selections produced with a tap or mouse down at the specified point. - Parameters: - point: The interaction point in the container coordinate system. - containerLocation: The location identifying which text container the point belongs to. - anchors: The last text selection state if 'selecting' is 'true' or the extend modifier is active. - modifiers: The active selection modifiers. - selecting: 'true' if currently in a text selection dragging session. - bounds: The view area in the container coordinate system that can interact with events (typically the view's visible area). - Returns: An array of text selections for the interaction. * @param point Argument converted to the Objective-C parameter of the same role. * @param container_location Argument converted to the Objective-C parameter of the same role. * @param anchors Argument converted to the Objective-C parameter of the same role. @@ -112,25 +105,21 @@ namespace cocoon std::vector text_selections_interacting_at_point(const Point& point, const Object& container_location, const std::vector& anchors, TextSelectionNavigationModifier modifiers, bool selecting, const Rect& bounds) const; /** * @brief Returns the `allowsNonContiguousRanges` property of `NSTextSelectionNavigation`. - * @details A Boolean value that indicates whether the object could produce selections with multiple disjoint ranges. * @return The converted Objective-C result. */ bool allows_non_contiguous_ranges() const; /** * @brief Sets the `allowsNonContiguousRanges` property of `NSTextSelectionNavigation`. - * @details A Boolean value that indicates whether the object could produce selections with multiple disjoint ranges. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_non_contiguous_ranges(bool value) const; /** * @brief Returns the `rotatesCoordinateSystemForLayoutOrientation` property of `NSTextSelectionNavigation`. - * @details A Boolean value that indicates whether the coordinate system rotates for navigation methods based on the text container layout orientation. The default value is 'false'. * @return The converted Objective-C result. */ bool rotates_coordinate_system_for_layout_orientation() const; /** * @brief Sets the `rotatesCoordinateSystemForLayoutOrientation` property of `NSTextSelectionNavigation`. - * @details A Boolean value that indicates whether the coordinate system rotates for navigation methods based on the text container layout orientation. The default value is 'false'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_rotates_coordinate_system_for_layout_orientation(bool value) const; diff --git a/include/generated/text_storage.h b/include/generated/text_storage.h index c7802625..891c76a6 100644 --- a/include/generated/text_storage.h +++ b/include/generated/text_storage.h @@ -57,7 +57,6 @@ namespace cocoon void add_layout_manager(const LayoutManager& a_layout_manager) const; /** * @brief Calls `-[NSTextStorage edited:range:changeInLength:]`. - * @details Tracks changes made to the text storage object, allowing the text storage to record the full extent of changes. If there are no outstanding 'beginEditing' calls, this method calls ''processEditing'' to trigger post-editing processes. This method has to be called by the primitives after changes are made if subclassed and overridden. 'editedRange' is the range in the original string (before the edit). - Parameters: - editedMask: The type of edit (attributes, characters, or both). - editedRange: The range in the original string before the edit. - delta: The change in length resulting from the edit. * @param edited_mask Argument converted to the Objective-C parameter of the same role. * @param edited_range Argument converted to the Objective-C parameter of the same role. * @param delta Argument converted to the Objective-C parameter of the same role. @@ -65,19 +64,16 @@ namespace cocoon void edited(TextStorageEditActions edited_mask, const Range& edited_range, std::int64_t delta) const; /** * @brief Calls `-[NSTextStorage ensureAttributesAreFixedInRange:]`. - * @details Ensures all attributes in the range are validated and ready to be used. A lazy 'NSTextStorage' is required to call this method before accessing any attributes. This gives the attribute fixing a chance to occur if necessary. Subclasses that wish to support laziness must call it from all attribute accessors that they implement. - Parameters: - range: The range to ensure attributes are fixed in. * @param range Argument converted to the Objective-C parameter of the same role. */ void ensure_attributes_are_fixed_in_range(const Range& range) const; /** * @brief Calls `-[NSTextStorage invalidateAttributesInRange:]`. - * @details Notes the range of attributes that requires validation. If the 'NSTextStorage' is not lazy this just calls 'fixAttributesInRange:'. If it is lazy this instead just records the range needing fixing in order to do it later. - Parameters: - range: The range of attributes to invalidate. * @param range Argument converted to the Objective-C parameter of the same role. */ void invalidate_attributes_in_range(const Range& range) const; /** * @brief Calls `-[NSTextStorage processEditing]`. - * @details Sends out delegate notifications, fixes the attributes, and notifies text storage observer of the change. Sends '-textStorage:willProcessEditing', fixes the attributes, sends '-textStorage:didProcessEditing', and notifies the text storage observer of change with '-processEditingForTextStorage:edited:range:changeInLength:invalidatedRange:'. Invoked from ''edited:range:changeInLength:'' or 'endEditing'. */ void process_editing() const; /** @@ -97,7 +93,6 @@ namespace cocoon void set_attribute_runs(const std::vector& value) const; /** * @brief Returns the `changeInLength` property of `NSTextStorage`. - * @details The difference between the current length of the edited range and its length before editing. * @return The converted Objective-C result. */ std::int64_t change_in_length() const; @@ -113,19 +108,16 @@ namespace cocoon void set_characters(const std::vector& value) const; /** * @brief Returns the `editedMask` property of `NSTextStorage`. - * @details A mask that describes the kinds of edits pending for the text storage object. * @return The converted Objective-C result. */ TextStorageEditActions edited_mask() const; /** * @brief Returns the `editedRange` property of `NSTextStorage`. - * @details The range of text that contains changes. '{NSNotFound, 0}' when there is no pending changes. * @return The converted Objective-C result. */ Range edited_range() const; /** * @brief Returns the `fixesAttributesLazily` property of `NSTextStorage`. - * @details A Boolean value that indicates whether the receiver fixes invalidated attributes lazily. The concrete UIKit subclass fixes attributes lazily by default. The abstract class (hence, all custom subclasses) is not lazy. * @return The converted Objective-C result. */ bool fixes_attributes_lazily() const; @@ -166,13 +158,11 @@ namespace cocoon void set_paragraphs(const std::vector& value) const; /** * @brief Returns the `textStorageObserver` property of `NSTextStorage`. - * @details An object conforming to 'NSTextStorageObserving' that observes and retains the text storage. * @return The converted Objective-C result. */ Object text_storage_observer() const; /** * @brief Sets the `textStorageObserver` property of `NSTextStorage`. - * @details An object conforming to 'NSTextStorageObserving' that observes and retains the text storage. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_text_storage_observer(const Object& value) const; diff --git a/include/generated/text_tab.h b/include/generated/text_tab.h index 420d2725..719671c7 100644 --- a/include/generated/text_tab.h +++ b/include/generated/text_tab.h @@ -26,8 +26,6 @@ namespace cocoon class TextTab : public Object { public: - /// @brief Creates a new `NSTextTab` instance and returns a handle to it. - explicit TextTab(TextAlignment alignment, double loc, const std::map& options); /// @brief Creates a new `NSTextTab` instance and returns a handle to it. explicit TextTab(TextTabType type, double loc); /// @brief Creates a new `NSTextTab` instance and returns a handle to it. @@ -38,26 +36,17 @@ namespace cocoon explicit TextTab(Adopt adopt); /** * @brief Calls `+[NSTextTab columnTerminatorsForLocale:]`. - * @details Returns the column terminators for the specified locale. The returned value can be used as the value for ''NSTextTab/OptionKey/columnTerminators'' to make a decimal tab stop. - Parameters: - aLocale: The locale to use when determining the terminators. Specify 'nil' to use the system's current locale. You can get the user's locale using the \ method of \. - Returns: The characters for the column terminators. * @param a_locale Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static CharacterSet column_terminators_for_locale(const Locale& a_locale); - /** - * @brief Returns the `alignment` property of `NSTextTab`. - * @details The text alignment of the text tab. 'NSTextAlignmentNatural' and 'NSTextAlignmentJustified' are resolved to either 'NSTextAlignmentLeft' or 'NSTextAlignmentRight' based on the user's preferred language. - * @return The converted Objective-C result. - */ - TextAlignment alignment() const; /** * @brief Returns the `location` property of `NSTextTab`. - * @details The text tab's ruler location relative to the back margin. * @return The converted Objective-C result. */ double location() const; /** * @brief Returns the `options` property of `NSTextTab`. - * @details The dictionary of attributes for the text tab. * @return The converted Objective-C result. */ std::map options() const; diff --git a/include/generated/text_table.h b/include/generated/text_table.h index 6d65b603..779296ec 100644 --- a/include/generated/text_table.h +++ b/include/generated/text_table.h @@ -15,6 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextTable` (AppKit). + * @details NSTextTable represents a table as a whole. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref TextBlock. * @@ -34,7 +35,7 @@ namespace cocoon * auto collapses_borders = text_table.collapses_borders(); * text_table.set_hides_empty_cells(true); * auto hides_empty_cells = text_table.hides_empty_cells(); - * text_table.set_layout_algorithm(cocoon::TextTableLayoutAlgorithm::Automatic); + * text_table.set_layout_algorithm(cocoon::TextTableLayoutAlgorithm::AutomaticLayoutAlgorithm); * auto layout_algorithm = text_table.layout_algorithm(); * @endcode * @see https://developer.apple.com/documentation/appkit/nstexttable @@ -113,12 +114,12 @@ namespace cocoon * @details These methods control the basic parameters of the table. * @return The converted Objective-C result. */ - std::int64_t number_of_columns() const; + std::uint64_t number_of_columns() const; /** * @brief Sets the `numberOfColumns` property of `NSTextTable`. * @details These methods control the basic parameters of the table. * @param value Argument converted to the Objective-C parameter of the same role. */ - void set_number_of_columns(std::int64_t value) const; + void set_number_of_columns(std::uint64_t value) const; }; } diff --git a/include/generated/text_table_block.h b/include/generated/text_table_block.h index f6a58604..45077dcc 100644 --- a/include/generated/text_table_block.h +++ b/include/generated/text_table_block.h @@ -12,6 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTextTableBlock` (AppKit). + * @details NSTextTableBlock is a subclass of NSTextBlock used for a block that appears as a cell in a text table. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref TextBlock. * @@ -27,7 +28,7 @@ namespace cocoon { public: /// @brief Creates a new `NSTextTableBlock` instance and returns a handle to it. - explicit TextTableBlock(const TextTable& table, std::int64_t row, std::int64_t row_span, std::int64_t column, std::int64_t column_span); + explicit TextTableBlock(const TextTable& table, std::int64_t row, std::int64_t row_span, std::int64_t col, std::int64_t col_span); /// @brief Creates a new `NSTextTableBlock` instance and returns a handle to it. explicit TextTableBlock(); /// @brief Creates a null handle that refers to no native object. diff --git a/include/generated/text_view.h b/include/generated/text_view.h index 33d1839f..7ba21243 100644 --- a/include/generated/text_view.h +++ b/include/generated/text_view.h @@ -27,11 +27,9 @@ namespace cocoon class TextCheckingResult; class TextContainer; class TextContentStorage; - class TextLayoutFragment; class TextLayoutManager; class TextRange; class TextStorage; - class TextViewportLayoutController; class URL; class UndoManager; class Value; @@ -364,16 +362,6 @@ namespace cocoon * @brief Calls `+[NSTextView registerForServices]`. */ static void register_for_services(); -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextView registerTextAttachmentViewProviderReusePolicy:forTextAttachmentViewProviderType:]`. - * @details Register the NSTextAttachmentViewProviderReusePolicy for all instances of a particular subclass of NSTextAttachmentViewProvider. - * @param policy Argument converted to the Objective-C parameter of the same role. - * @param view_provider_type Argument converted to the Objective-C parameter of the same role. - */ - void register_text_attachment_view_provider_reuse_policy(TextAttachmentViewProviderReusePolicy policy, const std::string& view_provider_type) const; -#endif - /** * @brief Calls `-[NSTextView replaceTextContainer:]`. * @param new_container Argument converted to the Objective-C parameter of the same role. @@ -538,43 +526,6 @@ namespace cocoon * @return The converted Objective-C result. */ static TextView text_view_using_text_layout_manager(bool using_text_layout_manager); -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextView textViewportLayoutController:configureRenderingSurfaceForTextLayoutFragment:]`. - * @details 'NSTextViewportLayoutControllerDelegate' method that the framework calls when the layout controller lays out a text layout fragment in the UI. Requires a call to super. - * @param text_viewport_layout_controller Argument converted to the Objective-C parameter of the same role. - * @param text_layout_fragment Argument converted to the Objective-C parameter of the same role. - */ - void text_viewport_layout_controller(const TextViewportLayoutController& text_viewport_layout_controller, const TextLayoutFragment& text_layout_fragment) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextView textViewportLayoutControllerDidLayout:]`. - * @details 'NSTextViewportLayoutControllerDelegate' method that the framework calls when the text viewport layout controller finishes its layout process. Requires a call to super. - * @param text_viewport_layout_controller Argument converted to the Objective-C parameter of the same role. - */ - void text_viewport_layout_controller_did_layout(const TextViewportLayoutController& text_viewport_layout_controller) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextView textViewportLayoutControllerReceivedSetNeedsLayout:]`. - * @details 'NSTextViewportLayoutControllerDelegate' method that the framework calls when the text viewport layout controller receives a 'setNeedsLayout' call. Requires a call to super. - * @param text_viewport_layout_controller Argument converted to the Objective-C parameter of the same role. - */ - void text_viewport_layout_controller_received_set_needs_layout(const TextViewportLayoutController& text_viewport_layout_controller) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextView textViewportLayoutControllerWillLayout:]`. - * @details 'NSTextViewportLayoutControllerDelegate' method that the framework calls when the text viewport layout controller starts its layout process. Requires a call to super. - * @param text_viewport_layout_controller Argument converted to the Objective-C parameter of the same role. - */ - void text_viewport_layout_controller_will_layout(const TextViewportLayoutController& text_viewport_layout_controller) const; -#endif - /** * @brief Calls `-[NSTextView tightenKerning:]`. * @param sender Argument converted to the Objective-C parameter of the same role. @@ -702,16 +653,6 @@ namespace cocoon * @return The converted Objective-C result. */ Object valid_requestor_for_send_type(const std::string& send_type, const std::string& return_type) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSTextView viewportBoundsForTextViewportLayoutController:]`. - * @details 'NSTextViewportLayoutControllerDelegate' method that the framework calls to request the current viewport, which is the view visible bounds plus the overdraw area. Requires a call to super. - * @param text_viewport_layout_controller Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - Rect viewport_bounds_for_text_viewport_layout_controller(const TextViewportLayoutController& text_viewport_layout_controller) const; -#endif - /** * @brief Calls `-[NSTextView writeSelectionToPasteboard:type:]`. * @param pboard Argument converted to the Objective-C parameter of the same role. diff --git a/include/generated/text_viewport_layout_controller.h b/include/generated/text_viewport_layout_controller.h index 0f75eea2..d07656ef 100644 --- a/include/generated/text_viewport_layout_controller.h +++ b/include/generated/text_viewport_layout_controller.h @@ -48,37 +48,31 @@ namespace cocoon explicit TextViewportLayoutController(Adopt adopt); /** * @brief Calls `-[NSTextViewportLayoutController adjustViewportByVerticalOffset:]`. - * @details Adjusts the viewport rect by the specified offset if needed. This is used to artificially move the viewport without affecting viewport content. The offset can be both positive and negative. - Parameters: - verticalOffset: The vertical offset to adjust by. * @param vertical_offset Argument converted to the Objective-C parameter of the same role. */ void adjust_viewport_by_vertical_offset(double vertical_offset) const; /** * @brief Calls `-[NSTextViewportLayoutController layoutViewport]`. - * @details Performs layout in the viewport. */ void layout_viewport() const; /** * @brief Calls `-[NSTextViewportLayoutController relocateViewportToTextLocation:]`. - * @details Relocates the viewport to start with the specified location. This is used to programmatically scroll to the specified location. - Parameters: - textLocation: The document location to scroll to. - Returns: The suggested viewport anchor point. * @param text_location Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double relocate_viewport_to_text_location(const Object& text_location) const; /** * @brief Returns the `textLayoutManager` property of `NSTextViewportLayoutController`. - * @details The text layout manager for this viewport layout controller. * @return The converted Objective-C result. */ TextLayoutManager text_layout_manager() const; /** * @brief Returns the `viewportBounds` property of `NSTextViewportLayoutController`. - * @details The visible bounds of the view, plus the overdraw area. Not KVO-compliant. * @return The converted Objective-C result. */ Rect viewport_bounds() const; /** * @brief Returns the `viewportRange` property of `NSTextViewportLayoutController`. - * @details The text range of the current viewport layout. Not KVO-compliant. * @return The converted Objective-C result. */ TextRange viewport_range() const; @@ -102,24 +96,6 @@ namespace cocoon { return Signal(handle(), "did_layout"); } -#ifdef COCOON_MACOS_27 - /// @brief Signal for the delegate/data-source method behind `cache_rendering_surface_for_key`; connect a callback with `cache_rendering_surface_for_key().connect(...)`. - Signal cache_rendering_surface_for_key() const - { - return Signal(handle(), "cache_rendering_surface_for_key"); - } -#endif - - /// @brief Signal for the delegate/data-source method behind `retrieve_cached_rendering_surface_for_key`; connect a callback with `retrieve_cached_rendering_surface_for_key().connect(...)`. - Signal retrieve_cached_rendering_surface_for_key() const - { - return Signal(handle(), "retrieve_cached_rendering_surface_for_key"); - } - /// @brief Signal for the delegate/data-source method behind `received_set_needs_layout`; connect a callback with `received_set_needs_layout().connect(...)`. - Signal received_set_needs_layout() const - { - return Signal(handle(), "received_set_needs_layout"); - } protected: static void install_delegate_delegate_(void* native); diff --git a/include/generated/thread.h b/include/generated/thread.h index e1c54758..308a49c4 100644 --- a/include/generated/thread.h +++ b/include/generated/thread.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSThread` (Foundation). - * @details A thread of execution. Use this class when you want to have an Objective-C method run in its own thread of execution. Threads are especially useful when you need to perform a lengthy task, but don't want it to block the execution of the rest of the application. In particular, you can use threads to avoid blocking the main thread of the application, which handles user interface and event-related actions. Threads can also be used to divide a large job into several smaller jobs, which can lead to performance increases on multi-core computers. The ''Thread'' class supports semantics similar to those of ''Operation'' for monitoring the runtime condition of a thread. You can use these semantics to cancel the execution of a thread or determine if the thread is still executing or has finished its task. Canceling a thread requires support from your thread code; see the description for ''cancel()'' for more information. \#\#\# Subclassing Notes You can subclass ''Thread'' and override the ''main()'' method to implement your thread's main entry point. If you override ''main()'', you do not need to invoke the inherited behavior by calling 'super'. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -54,12 +53,10 @@ namespace cocoon explicit Thread(Adopt adopt); /** * @brief Calls `-[NSThread cancel]`. - * @details Changes the cancelled state of the receiver to indicate that it should exit. The semantics of this method are the same as those used for 'NSOperation'. This method sets state information in the receiver that is then reflected by the 'isCancelled' property. Threads that support cancellation should periodically call the 'isCancelled' method to determine if the thread has in fact been cancelled, and exit if it has been. */ void cancel() const; /** * @brief Calls `+[NSThread detachNewThreadSelector:toTarget:withObject:]`. - * @details Detaches a new thread and uses the specified selector as the thread entry point. The objects 'aTarget' and 'anArgument' are retained during the execution of the detached thread, then released. The detached thread is exited (using the 'exit' class method) as soon as 'aTarget' has completed executing the 'aSelector' method. If this thread is the first thread detached in the application, this method posts the 'NSWillBecomeMultiThreaded' notification with object 'nil' to the default notification center. - Parameters: - selector: The selector for the message to send to the target. This selector must take only one argument and must not have a return value. - target: The object that will receive the message 'aSelector' on the new thread. - argument: The single argument passed to the target. May be 'nil'. * @param selector Argument converted to the Objective-C parameter of the same role. * @param target Argument converted to the Objective-C parameter of the same role. * @param argument Argument converted to the Objective-C parameter of the same role. @@ -72,94 +69,78 @@ namespace cocoon static void detach_new_thread_with_block(std::function block); /** * @brief Calls `+[NSThread exit]`. - * @details Terminates the current thread. This method uses the 'currentThread' class method to access the current thread. Before exiting the thread, this method posts the 'NSThreadWillExit' notification with the thread being exited to the default notification center. Because notifications are delivered synchronously, all observers of 'NSThreadWillExit' are guaranteed to receive the notification before the thread exits. Invoking this method should be avoided as it does not give your thread a chance to clean up any resources it allocated during its execution. */ static void exit(); /** * @brief Calls `+[NSThread isMultiThreaded]`. - * @details Returns whether the application is multithreaded. An application is considered multithreaded if a thread was ever detached from the main thread using either 'detachNewThreadSelector:toTarget:withObject:' or 'start'. If you detached a thread in your application using a non-Cocoa API, such as the POSIX or Multiprocessing Services APIs, this method could still return 'NO'. The detached thread does not have to be currently running for the application to be considered multithreaded -- this method only indicates whether a single thread has been spawned. - Returns: 'YES' if the application is multithreaded, otherwise 'NO'. * @return The converted Objective-C result. */ static bool is_multi_threaded(); /** * @brief Calls `-[NSThread main]`. - * @details The main entry point routine for the thread. The default implementation of this method takes the target and selector used to initialize the receiver and invokes the selector on the specified target. If you subclass 'NSThread', you can override this method and use it to implement the main body of your thread instead. If you do so, you do not need to invoke 'super'. You should never invoke this method directly. You should always start your thread by invoking the 'start' method. */ void main_() const; /** * @brief Calls `+[NSThread sleepForTimeInterval:]`. - * @details Sleeps the thread for a given time interval. No run loop processing occurs while the thread is blocked. - Parameter ti: The duration of the sleep. * @param ti Argument converted to the Objective-C parameter of the same role. */ static void sleep_for_time_interval(double ti); /** * @brief Calls `+[NSThread sleepUntilDate:]`. - * @details Blocks the current thread until the time specified. No run loop processing occurs while the thread is blocked. - Parameter date: The time at which to resume processing. * @param date Argument converted to the Objective-C parameter of the same role. */ static void sleep_until_date(const Date& date); /** * @brief Calls `-[NSThread start]`. - * @details Starts the receiver. This method asynchronously spawns the new thread and invokes the receiver's 'main' method on the new thread. The 'isExecuting' property returns 'YES' once the thread starts executing, which may occur after the 'start' method returns. If you initialized the receiver with a target and selector, the default 'main' method invokes that selector automatically. If this thread is the first thread detached in the application, this method posts the 'NSWillBecomeMultiThreaded' notification with object 'nil' to the default notification center. */ void start() const; /** * @brief Returns the `callStackReturnAddresses` property of `NSThread`. - * @details Returns an array containing the call stack return addresses. Each element is an 'NSNumber' object containing an 'NSUInteger' value. * @return The converted Objective-C result. */ static std::vector call_stack_return_addresses(); /** * @brief Returns the `callStackSymbols` property of `NSThread`. - * @details Returns an array containing the call stack symbols. Each element is an 'NSString' object with a value in a format determined by the 'backtrace_symbols()' function. The return value describes the call stack backtrace of the current thread at the moment this method was called. * @return The converted Objective-C result. */ static std::vector call_stack_symbols(); /** * @brief Returns the `cancelled` property of `NSThread`. - * @details A Boolean value that indicates whether the receiver is cancelled. If your thread supports cancellation, it should check this property periodically and exit if it ever returns 'YES'. * @return The converted Objective-C result. */ bool is_cancelled() const; /** * @brief Returns the `currentThread` property of `NSThread`. - * @details Returns the thread object representing the current thread of execution. * @return The converted Objective-C result. */ static Thread current_thread(); /** * @brief Returns the `executing` property of `NSThread`. - * @details A Boolean value that indicates whether the receiver is executing. * @return The converted Objective-C result. */ bool is_executing() const; /** * @brief Returns the `finished` property of `NSThread`. - * @details A Boolean value that indicates whether the receiver has finished execution. * @return The converted Objective-C result. */ bool is_finished() const; /** * @brief Returns the `isMainThread` property of `NSThread`. - * @details A Boolean value that indicates whether the receiver is the main thread. * @return The converted Objective-C result. */ bool is_main_thread() const; /** * @brief Returns the `mainThread` property of `NSThread`. - * @details Returns the 'NSThread' object representing the main thread. * @return The converted Objective-C result. */ static Thread main_thread(); /** * @brief Returns the `name` property of `NSThread`. - * @details The name of the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSThread`. - * @details The name of the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; @@ -175,31 +156,26 @@ namespace cocoon void set_quality_of_service(QualityOfService value) const; /** * @brief Returns the `stackSize` property of `NSThread`. - * @details The stack size of the receiver, in bytes. This value must be in bytes and a multiple of 4KB. To change the stack size, you must set this property before starting your thread. Setting the stack size after the thread has started changes the attribute size (which is reflected by the 'stackSize' method), but it does not affect the actual number of pages set aside for the thread. * @return The converted Objective-C result. */ std::uint64_t stack_size() const; /** * @brief Sets the `stackSize` property of `NSThread`. - * @details The stack size of the receiver, in bytes. This value must be in bytes and a multiple of 4KB. To change the stack size, you must set this property before starting your thread. Setting the stack size after the thread has started changes the attribute size (which is reflected by the 'stackSize' method), but it does not affect the actual number of pages set aside for the thread. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_stack_size(std::uint64_t value) const; /** * @brief Returns the `threadDictionary` property of `NSThread`. - * @details The thread object's dictionary. You can use the returned dictionary to store thread-specific data. The thread dictionary is not used during any manipulations of the 'NSThread' object -- it is simply a place where you can store any interesting data. For example, Foundation uses it to store the thread's default 'NSConnection' and 'NSAssertionHandler' instances. You may define your own keys for the dictionary. * @return The converted Objective-C result. */ std::vector> thread_dictionary() const; /** * @brief Returns the `threadPriority` property of `NSThread`. - * @details The receiver's priority. The thread's priority, which is specified by a floating point number from 0.0 to 1.0, where 1.0 is highest priority. The priorities in this range are mapped to the operating system's priority values. A "typical" thread priority might be 0.5, but because the priority is determined by the kernel, there is no guarantee what this value actually will be. * @return The converted Objective-C result. */ double thread_priority() const; /** * @brief Sets the `threadPriority` property of `NSThread`. - * @details The receiver's priority. The thread's priority, which is specified by a floating point number from 0.0 to 1.0, where 1.0 is highest priority. The priorities in this range are mapped to the operating system's priority values. A "typical" thread priority might be 0.5, but because the priority is determined by the kernel, there is no guarantee what this value actually will be. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_thread_priority(double value) const; diff --git a/include/generated/time_zone.h b/include/generated/time_zone.h index f7456026..4a6b13ec 100644 --- a/include/generated/time_zone.h +++ b/include/generated/time_zone.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTimeZone` (Foundation). - * @details Information about standard time conventions associated with a specific geopolitical region. In Swift, this type bridges to ''TimeZone''; use ''NSTimeZone'' when you need reference semantics or other Foundation-specific behavior. Time zones represent the standard time policies for a geopolitical region. Time zones have identifiers like "America/Los\\Angeles" and can also be identified by abbreviations, such as PST for Pacific Standard Time. You can create time zone objects by ID with ''init(name:)'' and by abbreviation with ''init(abbreviation:)''. > Note: > Time zone database entries such as "America/Los\\Angeles" are IDs, not names. An example of a time zone name is "Pacific Daylight Time". Although many ''NSTimeZone'' symbols include the word "name", they actually refer to IDs. Time zones can also represent a temporal offset—either plus or minus—from Greenwich Mean Time (GMT). For example, the temporal offset of Pacific Standard Time is 8 hours behind Greenwich Mean Time (GMT-8). You can create time zone objects with a temporal offset by using ''init(forSecondsFromGMT:)''. You typically work with system time zones rather than creating time zones by identifier or by offset. The ''system'' class property returns the time zone currently used by the system, if known. This value is cached once the property is accessed and doesn't reflect any system time zone changes until you call the ''resetSystemTimeZone()'' method. The ''local'' class property returns an autoupdating proxy object that always returns the current time zone used by the system. You can also set the ''default'' class property to make your app run as if it were in a different time zone than the system. > Tip: > You can't use ''NSTimeZone'' APIs to change the time zone of the device or of other apps. ''NSTimeZone'' is toll-free bridged with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. > Important: > The Swift overlay to the Foundation framework provides the ''TimeZone'' structure, which bridges to the ''NSTimeZone'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -57,35 +56,30 @@ namespace cocoon static std::map abbreviation_dictionary(); /** * @brief Calls `-[NSTimeZone abbreviationForDate:]`. - * @details Returns the abbreviation for the receiver at a given date. - Parameter aDate: The date for which to get the abbreviation for the receiver. - Returns: The abbreviation for the receiver at 'aDate'. Note that the abbreviation may be different at different dates. For example, during daylight saving time the US/Eastern time zone has an abbreviation of "EDT." At other times, its abbreviation is "EST." * @param a_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string abbreviation_for_date(const Date& a_date) const; /** * @brief Calls `-[NSTimeZone daylightSavingTimeOffsetForDate:]`. - * @details Returns the daylight saving time offset for a given date. - Parameter aDate: A date. - Returns: The daylight saving time offset for 'aDate'. * @param a_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double daylight_saving_time_offset_for_date(const Date& a_date) const; /** * @brief Calls `-[NSTimeZone isDaylightSavingTimeForDate:]`. - * @details Indicates whether the receiver uses daylight saving time on a given date. - Parameter aDate: The date against which to test the receiver. - Returns: 'YES' if the receiver uses daylight saving time at 'aDate', otherwise 'NO'. * @param a_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_daylight_saving_time_for_date(const Date& a_date) const; /** * @brief Calls `-[NSTimeZone isEqualToTimeZone:]`. - * @details Indicates whether the receiver has the same name and data as the specified time zone. - Parameter aTimeZone: The time zone to compare with the receiver. - Returns: 'YES' if 'aTimeZone' and the receiver have the same name and data, otherwise 'NO'. * @param a_time_zone Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool is_equal_to_time_zone(const TimeZone& a_time_zone) const; /** * @brief Calls `-[NSTimeZone localizedName:locale:]`. - * @details Returns the localized name of the time zone. - Parameter style: The format style for the returned string. - Parameter locale: The locale for which to format the name. - Returns: The name of the receiver localized for the given locale using the given style. * @param style Argument converted to the Objective-C parameter of the same role. * @param locale Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -93,111 +87,93 @@ namespace cocoon std::string localized_name(TimeZoneNameStyle style, const Locale& locale) const; /** * @brief Calls `-[NSTimeZone nextDaylightSavingTimeTransitionAfterDate:]`. - * @details Returns the next daylight saving time transition after a given date. - Parameter aDate: A date. - Returns: The next daylight saving time transition after 'aDate'. Depending on the time zone of the receiver, this method may return a change of the time zone's offset from GMT. Returns 'nil' if the time zone of the receiver does not observe daylight savings time as of 'aDate'. * @param a_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Date next_daylight_saving_time_transition_after_date(const Date& a_date) const; /** * @brief Calls `+[NSTimeZone resetSystemTimeZone]`. - * @details Clears any time zone value cached for the 'systemTimeZone' property. If the app has cached the system time zone by accessing the 'systemTimeZone' class property, this method clears that cached value. If you subsequently access 'systemTimeZone', a new time zone object is created and cached. */ static void reset_system_time_zone(); /** * @brief Calls `-[NSTimeZone secondsFromGMTForDate:]`. - * @details Returns the difference in seconds between the receiver and Greenwich Mean Time at a given date. - Parameter aDate: The date against which to test the receiver. - Returns: The difference in seconds between the receiver and Greenwich Mean Time at 'aDate'. The difference may be different from the current difference if the time zone changes its offset from GMT at different points in the year--for example, the U.S. time zones change with daylight saving time. * @param a_date Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::int64_t seconds_from_gmt_for_date(const Date& a_date) const; /** * @brief Calls `+[NSTimeZone timeZoneForSecondsFromGMT:]`. - * @details Returns a time zone object offset from Greenwich Mean Time by a given number of seconds. - Parameter seconds: The number of seconds by which the new time zone is offset from GMT. - Returns: A time zone object offset from Greenwich Mean Time by 'seconds'. The name of the new time zone is GMT +/- the offset, in hours and minutes. Time zones created with this method never have daylight savings, and the offset is constant no matter the date. * @param seconds Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static TimeZone time_zone_for_seconds_from_gmt(std::int64_t seconds); /** * @brief Returns the `abbreviation` property of `NSTimeZone`. - * @details The abbreviation for the receiver, such as "EDT" (Eastern Daylight Time). Invokes 'abbreviationForDate:' with the current date as the argument. * @return The converted Objective-C result. */ std::string abbreviation() const; /** * @brief Returns the `data` property of `NSTimeZone`. - * @details The data that stores the information used by the receiver. Treat this data as an opaque object. * @return The converted Objective-C result. */ std::vector data() const; /** * @brief Returns the `daylightSavingTime` property of `NSTimeZone`. - * @details A Boolean value that indicates whether the receiver is currently using daylight saving time. Invokes 'isDaylightSavingTimeForDate:' with the current date as the argument. * @return The converted Objective-C result. */ bool is_daylight_saving_time() const; /** * @brief Returns the `daylightSavingTimeOffset` property of `NSTimeZone`. - * @details The current daylight saving time offset of the receiver. * @return The converted Objective-C result. */ double daylight_saving_time_offset() const; /** * @brief Returns the `defaultTimeZone` property of `NSTimeZone`. - * @details The default time zone for the current app. If no default time zone has been set, the current system time zone is used. If the current system time zone cannot be determined, the GMT time zone is used instead. The default time zone is used by the app for date and time operations. You can set it to cause the app to run as if it were in a different time zone. Setting this property clears any value that was previously set. * @return The converted Objective-C result. */ static TimeZone default_time_zone(); /** * @brief Sets the `defaultTimeZone` property of `NSTimeZone`. - * @details The default time zone for the current app. If no default time zone has been set, the current system time zone is used. If the current system time zone cannot be determined, the GMT time zone is used instead. The default time zone is used by the app for date and time operations. You can set it to cause the app to run as if it were in a different time zone. Setting this property clears any value that was previously set. * @param value Argument converted to the Objective-C parameter of the same role. */ static void set_default_time_zone(const TimeZone& value); /** * @brief Returns the `description` property of `NSTimeZone`. - * @details A textual description of the time zone including the name, abbreviation, offset from GMT, and whether or not daylight saving time is currently in effect. * @return The converted Objective-C result. */ std::string description() const; /** * @brief Returns the `knownTimeZoneNames` property of `NSTimeZone`. - * @details Returns an array of strings listing the IDs of all the time zones known to the system. * @return The converted Objective-C result. */ static std::vector known_time_zone_names(); /** * @brief Returns the `localTimeZone` property of `NSTimeZone`. - * @details An object that tracks the current system time zone. Use this property when you want an object that always reflects the current system time zone. Contrast this behavior with that of the 'systemTimeZone' class property, which has its value cached until you manually clear it by calling ''resetSystemTimeZone''. * @return The converted Objective-C result. */ static TimeZone local_time_zone(); /** * @brief Returns the `name` property of `NSTimeZone`. - * @details The geopolitical region ID that identifies the receiver. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Returns the `nextDaylightSavingTimeTransition` property of `NSTimeZone`. - * @details The date of the next daylight saving time transition for the receiver. This property contains the date of the next (after the current instant) daylight saving time transition for the receiver. Depending on the time zone of the receiver, the value of this property may represent a change of the time zone's offset from GMT. Returns 'nil' if the time zone of the receiver does not currently observe daylight saving time. * @return The converted Objective-C result. */ Date next_daylight_saving_time_transition() const; /** * @brief Returns the `secondsFromGMT` property of `NSTimeZone`. - * @details The current difference in seconds between the receiver and Greenwich Mean Time. * @return The converted Objective-C result. */ std::int64_t seconds_from_gmt() const; /** * @brief Returns the `systemTimeZone` property of `NSTimeZone`. - * @details The time zone currently used by the system. If the current system time zone cannot be determined, the GMT time zone is used instead. If you access this class property, its value is cached by the app and doesn't update if the user subsequently changes the system time zone. In order for the property to reflect the new time zone, you must first call ''resetSystemTimeZone'' to clear the cached value. * @return The converted Objective-C result. */ static TimeZone system_time_zone(); /** * @brief Returns the `timeZoneDataVersion` property of `NSTimeZone`. - * @details Returns the time zone data version. * @return The converted Objective-C result. */ static std::string time_zone_data_version(); diff --git a/include/generated/timer.h b/include/generated/timer.h index ad7a55d4..a16b337d 100644 --- a/include/generated/timer.h +++ b/include/generated/timer.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSTimer` (Foundation). - * @details A timer that fires after a certain time interval has elapsed, sending a specified message to a target object. Timers work in conjunction with run loops. Run loops maintain strong references to their timers, so you don't have to maintain your own strong reference to a timer after you have added it to a run loop. To use a timer effectively, you should be aware of how run loops operate. See [Threading Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Multithreading/Introduction/Introduction.html\#//apple_ref/doc/uid/10000057i) for more information. A timer is not a real-time mechanism. If a timer's firing time occurs during a long run loop callout or while the run loop is in a mode that isn't monitoring the timer, the timer doesn't fire until the next time the run loop checks the timer. Therefore, the actual time at which a timer fires can be significantly later. See also \. ''Timer'' is toll-free bridged with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information. \#\#\# Comparing Repeating and Nonrepeating Timers You specify whether a timer is repeating or nonrepeating at creation time. A nonrepeating timer fires once and then invalidates itself automatically, thereby preventing the timer from firing again. By contrast, a repeating timer fires and then reschedules itself on the same run loop. A repeating timer always schedules itself based on the scheduled firing time, as opposed to the actual firing time. For example, if a timer is scheduled to fire at a particular time and every 5 seconds after that, the scheduled firing time will always fall on the original 5-second time intervals, even if the actual firing time gets delayed. If the firing time is delayed so far that it passes one or more of the scheduled firing times, the timer is fired only once for that time period; the timer is then rescheduled, after firing, for the next scheduled firing time in the future. \#\#\# Timer Tolerance In iOS 7 and later and macOS 10.9 and later, you can specify a tolerance for a timer (''tolerance''). This flexibility in when a timer fires improves the system's ability to optimize for increased power savings and responsiveness. The timer may fire at any time between its scheduled fire date and the scheduled fire date plus the tolerance. The timer doesn't fire before the scheduled fire date. For repeating timers, the next fire date is calculated from the original fire date regardless of tolerance applied at individual fire times, to avoid drift. The default value is zero, which means no additional tolerance is applied. The system reserves the right to apply a small amount of tolerance to certain timers regardless of the value of the ''tolerance'' property. As the user of the timer, you can determine the appropriate tolerance for a timer. A general rule, set the tolerance to at least 10\% of the interval, for a repeating timer. Even a small amount of tolerance has significant positive impact on the power usage of your application. The system may enforce a maximum value for the tolerance. \#\#\# Scheduling Timers in Run Loops You can register a timer in only one run loop at a time, although it can be added to multiple run loop modes within that run loop. There are three ways to create a timer: - Use the ''scheduledTimer(timeInterval:invocation:repeats:)'' or ''scheduledTimer(timeInterval:target:selector:userInfo:repeats:)'' class method to create the timer and schedule it on the current run loop in the default mode. - Use the ''init(timeInterval:invocation:repeats:)'' or ''init(timeInterval:target:selector:userInfo:repeats:)'' class method to create the timer object without scheduling it on a run loop. (After creating it, you must add the timer to a run loop manually by calling the ''RunLoop/add(:forMode:)-392ag'' method of the corresponding ''RunLoop'' object.) - Allocate the timer and initialize it using the ''init(fireAt:interval:target:selector:userInfo:repeats:)'' method. (After creating it, you must add the timer to a run loop manually by calling the ''RunLoop/add(:forMode:)-392ag'' method of the corresponding ''RunLoop'' object.) Once scheduled on a run loop, the timer fires at the specified interval until it is invalidated. A nonrepeating timer invalidates itself immediately after it fires. However, for a repeating timer, you must invalidate the timer object yourself by calling its ''invalidate()'' method. Calling this method requests the removal of the timer from the current run loop; as a result, you should always call the ''invalidate()'' method from the same thread on which the timer was installed. Invalidating the timer immediately disables it so that it no longer affects the run loop. The run loop then removes the timer (and the strong reference it had to the timer), either just before the ''invalidate()'' method returns or at some later point. Once invalidated, timer objects cannot be reused. After a repeating timer fires, it schedules the next firing for the nearest future date that is an integer multiple of the timer interval after the last scheduled fire date, within the specified ''tolerance''. If the time taken to call out to perform a selector or invocation is longer than the specified interval, the timer schedules only the next firing; that is, the timer doesn't attempt to compensate for any missed firings that would have occurred while calling the specified selector or invocation. \#\#\# Subclassing Notes Do not subclass ''Timer''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -59,17 +58,14 @@ namespace cocoon explicit Timer(Adopt adopt); /** * @brief Calls `-[NSTimer fire]`. - * @details Causes the timer's message to be sent to its target. You can use this method to fire a repeating timer without interrupting its regular firing schedule. If the timer is non-repeating, it is automatically invalidated after firing, even if its scheduled fire date has not arrived. */ void fire() const; /** * @brief Calls `-[NSTimer invalidate]`. - * @details Stops the timer from ever firing again and requests its removal from its run loop. This method is the only way to remove a timer from an 'NSRunLoop' object. The 'NSRunLoop' object removes its strong reference to the timer, either just before the -invalidate method returns or at some later point. If it was configured with target and user info objects, the receiver removes its strong references to those objects as well. You must send this message from the thread on which the timer was installed. If you send this message from another thread, the input source associated with the timer may not be removed from its run loop, which could prevent the thread from exiting properly. */ void invalidate() const; /** * @brief Calls `+[NSTimer scheduledTimerWithTimeInterval:invocation:repeats:]`. - * @details Creates a new timer and schedules it on the current run loop in the default mode. After 'ti' seconds have elapsed, the timer fires, invoking 'invocation'. - Parameters: - ti: The number of seconds between firings of the timer. If 'ti' is less than or equal to '0.0', this method chooses the nonnegative value of '0.0001' seconds instead. - invocation: The invocation to use when the timer fires. The invocation object maintains a strong reference to its arguments until the timer is invalidated. - yesOrNo: If 'YES', the timer will repeatedly reschedule itself until invalidated. If 'NO', the timer will be invalidated after it fires. - Returns: A new 'NSTimer' object, configured according to the specified parameters. * @param ti Argument converted to the Objective-C parameter of the same role. * @param invocation Argument converted to the Objective-C parameter of the same role. * @param yes_or_no Argument converted to the Objective-C parameter of the same role. @@ -87,7 +83,6 @@ namespace cocoon static Timer scheduled_timer_with_time_interval(double interval, bool repeats, std::function block); /** * @brief Calls `+[NSTimer scheduledTimerWithTimeInterval:target:selector:userInfo:repeats:]`. - * @details Creates a timer and schedules it on the current run loop in the default mode. After 'ti' seconds have elapsed, the timer fires, sending the message 'aSelector' to 'target'. - Parameters: - ti: The number of seconds between firings of the timer. If 'ti' is less than or equal to '0.0', this method chooses the nonnegative value of '0.0001' seconds instead. - aTarget: The object to which to send the message specified by 'aSelector' when the timer fires. The timer maintains a strong reference to 'target' until it (the timer) is invalidated. - aSelector: The message to send to 'target' when the timer fires. - userInfo: The user info for the timer. The timer maintains a strong reference to this object until it (the timer) is invalidated. This parameter may be 'nil'. - yesOrNo: If 'YES', the timer will repeatedly reschedule itself until invalidated. If 'NO', the timer will be invalidated after it fires. - Returns: A new 'NSTimer' object, configured according to the specified parameters. * @param ti Argument converted to the Objective-C parameter of the same role. * @param a_target Argument converted to the Objective-C parameter of the same role. * @param a_selector Argument converted to the Objective-C parameter of the same role. @@ -98,43 +93,36 @@ namespace cocoon static Timer scheduled_timer_with_time_interval(double ti, const Object& a_target, const std::string& a_selector, const Object& user_info, bool yes_or_no); /** * @brief Returns the `fireDate` property of `NSTimer`. - * @details The date at which the timer will fire. If the timer is no longer valid, the last date at which the timer fired. You can set this property to adjust the firing time of a repeating timer. Although resetting a timer's next firing time is a relatively expensive operation, it may be more efficient in some situations. For example, you could use it in situations where you want to repeat an action multiple times in the future, but at irregular time intervals. Adjusting the firing time of a single timer would likely incur less expense than creating multiple timer objects, scheduling each one on a run loop, and then destroying them. You should not change the fire date of a timer that has been invalidated, which includes non-repeating timers that have already fired. You could potentially change the fire date of a non-repeating timer that had not yet fired, although you should always do so from the thread to which the timer is attached to avoid potential race conditions. * @return The converted Objective-C result. */ Date fire_date() const; /** * @brief Sets the `fireDate` property of `NSTimer`. - * @details The date at which the timer will fire. If the timer is no longer valid, the last date at which the timer fired. You can set this property to adjust the firing time of a repeating timer. Although resetting a timer's next firing time is a relatively expensive operation, it may be more efficient in some situations. For example, you could use it in situations where you want to repeat an action multiple times in the future, but at irregular time intervals. Adjusting the firing time of a single timer would likely incur less expense than creating multiple timer objects, scheduling each one on a run loop, and then destroying them. You should not change the fire date of a timer that has been invalidated, which includes non-repeating timers that have already fired. You could potentially change the fire date of a non-repeating timer that had not yet fired, although you should always do so from the thread to which the timer is attached to avoid potential race conditions. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_fire_date(const Date& value) const; /** * @brief Returns the `timeInterval` property of `NSTimer`. - * @details The timer's time interval, in seconds. If the timer is non-repeating, returns '0' even if a time interval was set. * @return The converted Objective-C result. */ double time_interval() const; /** * @brief Returns the `tolerance` property of `NSTimer`. - * @details The amount of time after the scheduled fire date that the timer may fire. The default value is zero, which means no additional tolerance is applied. Setting a tolerance for a timer allows it to fire later than the scheduled fire date. Allowing the system flexibility in when a timer fires increases the ability of the system to optimize for increased power savings and responsiveness. The timer may fire at any time between its scheduled fire date and the scheduled fire date plus the tolerance. The timer will not fire before the scheduled fire date. For repeating timers, the next fire date is calculated from the original fire date regardless of tolerance applied at individual fire times, to avoid drift. The system reserves the right to apply a small amount of tolerance to certain timers regardless of the value of this property. * @return The converted Objective-C result. */ double tolerance() const; /** * @brief Sets the `tolerance` property of `NSTimer`. - * @details The amount of time after the scheduled fire date that the timer may fire. The default value is zero, which means no additional tolerance is applied. Setting a tolerance for a timer allows it to fire later than the scheduled fire date. Allowing the system flexibility in when a timer fires increases the ability of the system to optimize for increased power savings and responsiveness. The timer may fire at any time between its scheduled fire date and the scheduled fire date plus the tolerance. The timer will not fire before the scheduled fire date. For repeating timers, the next fire date is calculated from the original fire date regardless of tolerance applied at individual fire times, to avoid drift. The system reserves the right to apply a small amount of tolerance to certain timers regardless of the value of this property. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tolerance(double value) const; /** * @brief Returns the `userInfo` property of `NSTimer`. - * @details The receiver's 'userInfo' object. Do not access this property after the timer is invalidated. Use the 'isValid' method to test whether the timer is valid. * @return The converted Objective-C result. */ Object user_info() const; /** * @brief Returns the `valid` property of `NSTimer`. - * @details A Boolean value that indicates whether the timer is currently valid. 'YES' if the receiver is still capable of firing or 'NO' if the timer has been invalidated and is no longer capable of firing. * @return The converted Objective-C result. */ bool is_valid() const; diff --git a/include/generated/titlebar_accessory_view_controller.h b/include/generated/titlebar_accessory_view_controller.h index b42eb5b3..47941c7c 100644 --- a/include/generated/titlebar_accessory_view_controller.h +++ b/include/generated/titlebar_accessory_view_controller.h @@ -102,13 +102,13 @@ namespace cocoon void set_hidden(bool value) const; /** * @brief Returns the `layoutAttribute` property of `NSTitlebarAccessoryViewController`. - * @details The layoutAttribute defaults to NSLayoutAttributeBottom, telling the window to place this view controller's view under the titlebar. NSLayoutAttributeRight is also supported, telling the window to place the view controller's view on the right side of the window. For applications linked on Mac OS 10.11 or later, NSLayoutAttributeLeft is also supported; placing the item on the left side of the window (adjacent and to the right of the close/minimize/maximize buttons). All other values are currently invalid and will assert. A layoutAttribute == NSLayoutAttributeRight will indent toolbar items for all toolbar styles except NSToolbarStyleExpanded and NSToolbarStyleCompact. For applications linked on 10.12 and higher, NSLayoutAttributeLeading and NSLayoutAttributeTrailing can also be used to specify an abstract position that automatically flips depending on the localized language. For applications that do not link on 10.12, NSLayoutAttributeLeft will automatically flip to the Right when in a Right To Left language. For applications linked on 10.13 and higher, NSLayoutAttributeTop can also be used to specify a view that will be at the top of the titlebar area. Only one should be used per window, and if one is set the normal titlebar will not be drawn. Using the top attributed requires the window to have the NSWindowStyleMaskFullSizeContentView style mask set. The "hidden" property can be used to show and hide the view. The "hidden" property will animate the view via an alpha fade in and out if accessed through the animator proxy (such as: viewController.animator.hidden = YES). For applications linked on macOS 27.0 or higher, leading and trailing accessories are positioned within the titlebar area only (excluding the toolbar) when the window uses NSWindowToolbarStyleExpanded or NSWindowToolbarStylePreference, or when the window has no toolbar. + * @details The layoutAttribute defaults to NSLayoutAttributeBottom, telling the window to place this view controller's view under the titlebar. NSLayoutAttributeRight is also supported, telling the window to place the view controller's view on the right side of the window. For applications linked on Mac OS 10.11 or later, NSLayoutAttributeLeft is also supported; placing the item on the left side of the window (adjacent and to the right of the close/minimize/maximize buttons). All other values are currently invalid and will assert. A layoutAttribute == NSLayoutAttributeRight will indent toolbar items for all toolbar styles except NSToolbarStyleExpanded and NSToolbarStyleCompact. For applications linked on 10.12 and higher, NSLayoutAttributeLeading and NSLayoutAttributeTrailing can also be used to specify an abstract position that automatically flips depending on the localized language. For applications that do not link on 10.12, NSLayoutAttributeLeft will automatically flip to the Right when in a Right To Left language. For applications linked on 10.13 and higher, NSLayoutAttributeTop can also be used to specify a view that will be at the top of the titlebar area. Only one should be used per window, and if one is set the normal titlebar will not be drawn. Using the top attributed requires the window to have the NSWindowStyleMaskFullSizeContentView style mask set. The "hidden" property can be used to show and hide the view. The "hidden" property will animate the view via an alpha fade in and out if accessed through the animator proxy (such as: viewController.animator.hidden = YES). * @return The converted Objective-C result. */ LayoutAttribute layout_attribute() const; /** * @brief Sets the `layoutAttribute` property of `NSTitlebarAccessoryViewController`. - * @details The layoutAttribute defaults to NSLayoutAttributeBottom, telling the window to place this view controller's view under the titlebar. NSLayoutAttributeRight is also supported, telling the window to place the view controller's view on the right side of the window. For applications linked on Mac OS 10.11 or later, NSLayoutAttributeLeft is also supported; placing the item on the left side of the window (adjacent and to the right of the close/minimize/maximize buttons). All other values are currently invalid and will assert. A layoutAttribute == NSLayoutAttributeRight will indent toolbar items for all toolbar styles except NSToolbarStyleExpanded and NSToolbarStyleCompact. For applications linked on 10.12 and higher, NSLayoutAttributeLeading and NSLayoutAttributeTrailing can also be used to specify an abstract position that automatically flips depending on the localized language. For applications that do not link on 10.12, NSLayoutAttributeLeft will automatically flip to the Right when in a Right To Left language. For applications linked on 10.13 and higher, NSLayoutAttributeTop can also be used to specify a view that will be at the top of the titlebar area. Only one should be used per window, and if one is set the normal titlebar will not be drawn. Using the top attributed requires the window to have the NSWindowStyleMaskFullSizeContentView style mask set. The "hidden" property can be used to show and hide the view. The "hidden" property will animate the view via an alpha fade in and out if accessed through the animator proxy (such as: viewController.animator.hidden = YES). For applications linked on macOS 27.0 or higher, leading and trailing accessories are positioned within the titlebar area only (excluding the toolbar) when the window uses NSWindowToolbarStyleExpanded or NSWindowToolbarStylePreference, or when the window has no toolbar. + * @details The layoutAttribute defaults to NSLayoutAttributeBottom, telling the window to place this view controller's view under the titlebar. NSLayoutAttributeRight is also supported, telling the window to place the view controller's view on the right side of the window. For applications linked on Mac OS 10.11 or later, NSLayoutAttributeLeft is also supported; placing the item on the left side of the window (adjacent and to the right of the close/minimize/maximize buttons). All other values are currently invalid and will assert. A layoutAttribute == NSLayoutAttributeRight will indent toolbar items for all toolbar styles except NSToolbarStyleExpanded and NSToolbarStyleCompact. For applications linked on 10.12 and higher, NSLayoutAttributeLeading and NSLayoutAttributeTrailing can also be used to specify an abstract position that automatically flips depending on the localized language. For applications that do not link on 10.12, NSLayoutAttributeLeft will automatically flip to the Right when in a Right To Left language. For applications linked on 10.13 and higher, NSLayoutAttributeTop can also be used to specify a view that will be at the top of the titlebar area. Only one should be used per window, and if one is set the normal titlebar will not be drawn. Using the top attributed requires the window to have the NSWindowStyleMaskFullSizeContentView style mask set. The "hidden" property can be used to show and hide the view. The "hidden" property will animate the view via an alpha fade in and out if accessed through the animator proxy (such as: viewController.animator.hidden = YES). * @param value Argument converted to the Objective-C parameter of the same role. */ void set_layout_attribute(LayoutAttribute value) const; diff --git a/include/generated/toolbar_item_group.h b/include/generated/toolbar_item_group.h index c702ee45..f25f8a7f 100644 --- a/include/generated/toolbar_item_group.h +++ b/include/generated/toolbar_item_group.h @@ -30,10 +30,10 @@ namespace cocoon * cocoon::ToolbarItemGroup toolbar_item_group{}; * toolbar_item_group.set_control_representation(cocoon::ToolbarItemGroupControlRepresentation::Automatic); * auto control_representation = toolbar_item_group.control_representation(); - * toolbar_item_group.set_role(cocoon::ToolbarItemGroupRole::Automatic); - * auto role = toolbar_item_group.role(); * toolbar_item_group.set_selected_index(1); * auto selected_index = toolbar_item_group.selected_index(); + * toolbar_item_group.set_selection_mode(cocoon::ToolbarItemGroupSelectionMode::SelectOne); + * auto selection_mode = toolbar_item_group.selection_mode(); * toolbar_item_group.is_selected_at_index(1); * toolbar_item_group.set_selected(true, 1); * @endcode @@ -96,24 +96,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_control_representation(ToolbarItemGroupControlRepresentation value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `role` property of `NSToolbarItemGroup`. - * @details The semantic role of the item. Defaults to 'NSToolbarItemGroupRoleAutomatic'. - * @return The converted Objective-C result. - */ - ToolbarItemGroupRole role() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `role` property of `NSToolbarItemGroup`. - * @details The semantic role of the item. Defaults to 'NSToolbarItemGroupRoleAutomatic'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_role(ToolbarItemGroupRole value) const; -#endif - /** * @brief Returns the `selectedIndex` property of `NSToolbarItemGroup`. * @details The most recently selected item of the group, or -1 if nothing is selected. diff --git a/include/generated/ubiquitous_key_value_store.h b/include/generated/ubiquitous_key_value_store.h index 0d5ea96c..5cc4c49f 100644 --- a/include/generated/ubiquitous_key_value_store.h +++ b/include/generated/ubiquitous_key_value_store.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUbiquitousKeyValueStore` (Foundation). - * @details An iCloud-based container of key-value pairs you share among instances of your app running on a person’s devices. Use the shared 'NSUbiquitousKeyValueStore' object to store settings, configuration information, and app-specific data in a person’s iCloud account and share it among instances of your app running on all of the person’s devices. The object stores a dictionary of key-value pairs that you provide, and propagates that data to devices with the same Apple account. Sharing data among different devices gives you a way to coordinate your app’s behavior on those devices. For example, a textbook app might save the current page number on someone’s iPhone so that the person can continue reading from the same place on their other devices. > Important: Don't store personal or sensitive information in the key-value store. The system stores the information on disk in an unencrypted format. Store personal or sensitive information in the person's Keychain instead. Each app has a single iCloud key-value store object, which you retrieve from the ''NSUbiquitousKeyValueStore/default'' class property. Use this same object throughout your app to read and write values. Don’t subclass 'NSUbiquitousKeyValueStore'. > Note: To use this object, you must distribute your app through the App Store or Mac App Store, and you must request the [iCloud key-value store entitlement](\) in your Xcode project. The keys in the iCloud key-value store identify the item and its purpose in your app, and the value is a data object you use to implement the corresponding behavior in your app. Values must be property list types such as \, \, \, \, \, \, ''Date'', \, or \. To include other types of objects in the key-value store, archive them to a ''Data'' object first and store that object instead. Prefer simple types over custom objects whenever possible. When you write a new value, the iCloud key-value store saves it in memory initially and writes it to disk asynchronously later. If the device doesn’t have an active Apple account, the changes remain only on the current device. When the person signs into their account, the system forwards any changes to the iCloud server and reconciles the values there with the local ones. As you make more changes, the system keeps the local and server-based copies of the data synchronized, updating each one at appropriate times. When a value changes on one device, iCloud forwards that change to the person’s other devices. If your app is running on one of those other devices, the system posts ''NSUbiquitousKeyValueStore/didChangeExternallyNotification'' to report the change. Register for that notification to keep all instances of your app in sync. When designing the keys and values you intend to save for your app, consider the following size limitations: Your app can have no more than 1024 keys in the iCloud key-value store. The total amount of available storage space for all values is 1 megabyte. The maximum size for a single value is 1 megabyte. Therefore, if you associate 1 megabyte of data with a single key, you can’t write other keys to the store. The maximum length for each key string is 128 characters using the UTF-16 encoding. Key strings don’t count against the 1 megabyte quota for values. If you exceed any of the prescribed limits during a write operation, the operation fails and the system doesn’t add the keys or values to the store. If a key string exceeds the maximum length, the system raises an exception. If a write operation would exceed your app’s quota, the system posts ''NSUbiquitousKeyValueStore/didChangeExternallyNotification'' notification with the change reason set to ''NSUbiquitousKeyValueStoreQuotaViolationChange''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -41,137 +40,117 @@ namespace cocoon explicit UbiquitousKeyValueStore(Adopt adopt); /** * @brief Calls `-[NSUbiquitousKeyValueStore arrayForKey:]`. - * @details Returns the array associated with the specified key. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector array_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore boolForKey:]`. - * @details Returns the Boolean value associated with the specified key. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool bool_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore dataForKey:]`. - * @details Returns the data object associated with the specified key. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector data_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore dictionaryForKey:]`. - * @details Returns the dictionary object associated with the specified key. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map dictionary_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore doubleForKey:]`. - * @details Returns the 'double' value associated with the specified key. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double double_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore longLongForKey:]`. - * @details Returns the 64-bit integer value associated with the specified key. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::int64_t long_long_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore objectForKey:]`. - * @details Returns the object associated with the specified key. - Parameter aKey: The key to retrieve from the iCloud key-value store. - Returns: The object associated with 'aKey', or 'nil' if the key isn't present. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object object_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore removeObjectForKey:]`. - * @details Removes the value for the specified key from the iCloud key-value store. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void remove_object_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setArray:forKey:]`. - * @details Sets the value of the specified key to an array of property list objects. * @param an_array Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_array(const std::vector& an_array, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setBool:forKey:]`. - * @details Sets the value of the specified key to a Boolean value. * @param value Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_bool(bool value, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setData:forKey:]`. - * @details Sets the value of the specified key to a data object. * @param a_data Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_data(const std::vector& a_data, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setDictionary:forKey:]`. - * @details Sets the value of the specified key to a dictionary of property list objects. * @param a_dictionary Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_dictionary(const std::map& a_dictionary, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setDouble:forKey:]`. - * @details Sets the value of the specified key to a double value. * @param value Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_double(double value, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setLongLong:forKey:]`. - * @details Sets the value of the specified key to a 64-bit integer value. * @param value Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_long_long(std::int64_t value, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setObject:forKey:]`. - * @details Sets the value of the specified key to a property list object. * @param an_object Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_object(const Object& an_object, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore setString:forKey:]`. - * @details Sets the value of the specified key to a string value. * @param a_string Argument converted to the Objective-C parameter of the same role. * @param a_key Argument converted to the Objective-C parameter of the same role. */ void set_string(const std::string& a_string, const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore stringForKey:]`. - * @details Returns the string associated with the specified key. * @param a_key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_for_key(const std::string& a_key) const; /** * @brief Calls `-[NSUbiquitousKeyValueStore synchronize]`. - * @details Synchronizes the in-memory keys and values with the ones stored in iCloud. - Returns: 'YES' if the in-memory and iCloud keys are synchronized, or 'NO' if an error occurred. * @return The converted Objective-C result. */ bool synchronize() const; /** * @brief Returns the `defaultStore` property of `NSUbiquitousKeyValueStore`. - * @details The shared iCloud key-value store object. Use this object to access the shared iCloud key-value store tied to your app and the current person. * @return The converted Objective-C result. */ static UbiquitousKeyValueStore default_store(); /** * @brief Returns the `dictionaryRepresentation` property of `NSUbiquitousKeyValueStore`. - * @details A dictionary with all of the key-value pairs in the iCloud key-value store. * @return The converted Objective-C result. */ std::map dictionary_representation() const; diff --git a/include/generated/unarchiver.h b/include/generated/unarchiver.h index b448ab48..60407693 100644 --- a/include/generated/unarchiver.h +++ b/include/generated/unarchiver.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnarchiver` (Foundation). - * @details A decoder that restores data from an archive. ''NSUnarchiver'', a concrete subclass of ''NSCoder'', defines methods for decoding a set of Objective-C objects from an archive. Such archives are produced by objects of the ''NSArchiver'' class. In macOS 10.2 and later, ''NSArchiver'' and ''NSUnarchiver'' have been replaced by ''NSKeyedArchiver'' and ''NSKeyedUnarchiver'' respectively—see [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html\#//apple_ref/doc/uid/10000047i). \@DeprecationSummary { Use ''NSKeyedUnarchiver'' instead. } + * @details Archiving: Reading * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Coder. * @@ -44,48 +44,41 @@ namespace cocoon using Coder::system_version; /** * @brief Calls `-[NSUnarchiver classNameDecodedForArchiveClassName:]`. - * @details Returns the class name that this unarchiver substitutes for a given archived class name. Returns 'inArchiveName' unless a substitute name has been specified using the instance method ''decodeClassName:asClassName:''. - Parameter inArchiveName: The name of a class. - Returns: The name of the class used when instantiating objects whose ostensible class, according to the archived data, is 'inArchiveName'. * @param in_archive_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string class_name_decoded_for_archive_class_name(const std::string& in_archive_name) const; /** * @brief Calls `-[NSUnarchiver decodeClassName:asClassName:]`. - * @details Sets a per-instance substitution mapping, translating a given class name from the archive to a given replacement class name during decoding. This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created. Note that there's also a class method of the same name. The class method has precedence in case of conflicts. - Parameters: - inArchiveName: The ostensible name of a class in an archive. - trueName: The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is 'inArchiveName'. * @param in_archive_name Argument converted to the Objective-C parameter of the same role. * @param true_name Argument converted to the Objective-C parameter of the same role. */ void decode_class_name(const std::string& in_archive_name, const std::string& true_name) const; /** * @brief Calls `-[NSUnarchiver replaceObject:withObject:]`. - * @details Replaces one object with another during decoding. Causes the receiver to substitute 'newObject' for 'object' whenever 'object' is extracted from the archive. 'newObject' can be of a different class from 'object', and the class mappings set by ''decodeClassName:asClassName:'' are ignored. - Parameters: - object: The archived object to replace. - newObject: The object with which to replace 'object'. * @param object Argument converted to the Objective-C parameter of the same role. * @param new_object Argument converted to the Objective-C parameter of the same role. */ void replace_object(const Object& object, const Object& new_object) const; /** * @brief Calls `+[NSUnarchiver unarchiveObjectWithData:]`. - * @details Decodes and returns the previously-archived object graph in the given data. This method invokes ''NSUnarchiver/initForReadingWithData:'' and ''NSCoder/decodeObject'' to create a temporary 'NSUnarchiver' object that decodes the object. If the archived object is the root of a graph of objects, the entire graph is unarchived. - Parameter data: An 'NSData' object that contains an archive created using 'NSArchiver'. - Returns: The object, or object graph, that was archived in 'data'. Returns 'nil' if 'data' cannot be unarchived. * @param data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object unarchive_object_with_data(const std::vector& data); /** * @brief Calls `+[NSUnarchiver unarchiveObjectWithFile:]`. - * @details Decodes and returns the previously-archived object graph from the file at the given path. This convenience method reads the file by invoking the 'NSData' method ''NSData/dataWithContentsOfFile:'' and then invokes ''NSUnarchiver/unarchiveObjectWithData:''. - Parameter path: The path to a file that contains an archive created using ''NSArchiver''. - Returns: The object, or object graph, that was archived in the file at 'path'. Returns 'nil' if the file at 'path' cannot be unarchived. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object unarchive_object_with_file(const std::string& path); /** * @brief Returns the `atEnd` property of `NSUnarchiver`. - * @details A Boolean value that indicates whether the receiver has reached the end of the encoded data while decoding. You can invoke this after invoking 'decodeObject' to discover whether the archive contains extra data following the encoded object graph. If it does, you can either ignore this anomaly or consider it an error. * @return The converted Objective-C result. */ bool is_at_end() const; /** * @brief Returns the `systemVersion` property of `NSUnarchiver`. - * @details The system version number in effect when the archive was created. This information is available as soon as the receiver has been initialized. * @return The converted Objective-C result. */ unsigned int system_version() const; diff --git a/include/generated/undo_manager.h b/include/generated/undo_manager.h index 8a566c9a..fcb0fa56 100644 --- a/include/generated/undo_manager.h +++ b/include/generated/undo_manager.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUndoManager` (Foundation). - * @details A general-purpose recorder of operations that enables undo and redo. You register an undo operation by calling one of the methods described in Registering undo operations. You specify the name of the object that's changing (or the owner of that object) and provide a closure, method, or invocation to revert its state. After you register an undo operation, you can call ''undo()'' on the undo manager to revert to the state of the last undo operation. When undoing an action, ''UndoManager'' saves the operations you revert to so that you can call ''redo()'' automatically. Typically, apps with UI interactions work with ''UndoManager''. For example, UIKit implements undo and redo in its text view object, making it easy for you to undo and redo actions in objects along the responder chain. ''UndoManager'' also serves as a general-purpose state manager, which you can use to undo and redo many kinds of actions. For example, an interactive command-line utility can use this class to undo the last command run, or a networking library can undo a request by sending another request that invalidates the previous one. > Important: 'UndoManager' is \-isolated in Swift, making it safe to use in UI frameworks like \ and \ that expect to execute code on the main thread, queue, or actor. When registering an undoable action with ''registerUndo(withTarget:handler:)'', the 'handler' closure is also \-isolated to ensure safety and simplify ergonomics. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -53,7 +52,7 @@ namespace cocoon void begin_undo_grouping() const; /** * @brief Calls `-[NSUndoManager disableUndoRegistration]`. - * @details Disables the recording of undo operations. This method can be invoked multiple times by multiple clients. The ''enableUndoRegistration'' method must be invoked an equal number of times to re-enable undo registration. + * @details Disables the recording of undo operations, whether by ''registerUndoWithTarget:selector:object:'' or by invocation-based undo. This method can be invoked multiple times by multiple clients. The ''enableUndoRegistration'' method must be invoked an equal number of times to re-enable undo registration. */ void disable_undo_registration() const; /** @@ -80,21 +79,21 @@ namespace cocoon void redo() const; /** * @brief Calls `-[NSUndoManager redoActionUserInfoValueForKey:]`. - * @details Retrieves the redo action's user info value for the given key. - Parameter key: Which value should be retrieved + * @details Get a value from the redo action's user info - Parameter key: Which value should be retrieved * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object redo_action_user_info_value_for_key(const std::string& key) const; /** * @brief Calls `-[NSUndoManager redoMenuTitleForUndoActionName:]`. - * @details Returns the localized title of the Redo menu command for the identified action. Override this method if you want to customize the localization behaviour. This method is invoked by ''redoMenuItemTitle''. - Parameter actionName: The name of the redo action. - Returns: The localized title of the redo menu item. + * @details Returns the complete, localized title of the Redo menu command for the action identified by the given name. Override this method if you want to customize the localization behaviour. This method is invoked by ''redoMenuItemTitle''. - Parameter actionName: The name of the redo action. - Returns: The localized title of the redo menu item. * @param action_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string redo_menu_title_for_undo_action_name(const std::string& action_name) const; /** * @brief Calls `-[NSUndoManager registerUndoWithTarget:handler:]`. - * @details Registers the specified closure to implement a single undo operation that the target receives. As with other undo operations, this does not strongly retain target. Care should be taken to avoid introducing retain cycles by other references captured by the block. - Parameter target: The target of the undo operation. - Parameter undoHandler: The block to be executed when an operation is undone. The block takes a single argument, the target of the undo operation. + * @details Records a single undo operation for a given target so that when an undo is performed, it executes the specified block. As with other undo operations, this does not strongly retain target. Care should be taken to avoid introducing retain cycles by other references captured by the block. - Parameter target: The target of the undo operation. - Parameter undoHandler: The block to be executed when an operation is undone. The block takes a single argument, the target of the undo operation. * @param target Argument converted to the Objective-C parameter of the same role. * @param undo_handler Argument converted to the Objective-C parameter of the same role. */ @@ -109,7 +108,7 @@ namespace cocoon void register_undo_with_target(const Object& target, const std::string& selector, const Object& object) const; /** * @brief Calls `-[NSUndoManager removeAllActions]`. - * @details Clears the undo and redo stacks and reenables the manager. + * @details Clears the undo and redo stacks and re-enables the receiver. */ void remove_all_actions() const; /** @@ -132,26 +131,26 @@ namespace cocoon void set_action_name(const std::string& action_name) const; /** * @brief Calls `-[NSUndoManager setActionUserInfoValue:forKey:]`. - * @details Sets a user info value for an undo or redo action. - Parameter info: Value to be saved in the user info - Parameter key: Key at which the object should be saved + * @details Set user info for the Undo or Redo command. - Parameter info: Value to be saved in the user info - Parameter key: Key at which the object should be saved * @param info Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void set_action_user_info_value(const Object& info, const std::string& key) const; /** * @brief Calls `-[NSUndoManager undo]`. - * @details Closes the top-level undo group if necessary, and then performs undo operations on the group. This method also invokes ''endUndoGrouping'' if the nesting level is 1. Raises an ''NSInternalInconsistencyException'' if more than one undo group is open (that is, if the last group isn’t at the top level). This method posts an ''NSUndoManagerCheckpointNotification''. + * @details Closes the top-level undo group if necessary and invokes ''undoNestedGroup''. This method also invokes ''endUndoGrouping'' if the nesting level is 1. Raises an ''NSInternalInconsistencyException'' if more than one undo group is open (that is, if the last group isn’t at the top level). This method posts an ''NSUndoManagerCheckpointNotification''. */ void undo() const; /** * @brief Calls `-[NSUndoManager undoActionUserInfoValueForKey:]`. - * @details Retrieves the undo action's user info value for the given key. - Parameter key: Which value should be retrieved + * @details Get a value from the undo action's user info - Parameter key: Which value should be retrieved * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object undo_action_user_info_value_for_key(const std::string& key) const; /** * @brief Calls `-[NSUndoManager undoMenuTitleForUndoActionName:]`. - * @details Returns the localized title of the Undo menu command for the identified action. Override this method if you want to customize the localization behaviour. This method is invoked by ''undoMenuItemTitle''. - Parameter actionName: The name of the undo action. - Returns: The localized title of the undo menu item. + * @details Returns the complete, localized title of the Undo menu command for the action identified by the given name. Override this method if you want to customize the localization behaviour. This method is invoked by ''undoMenuItemTitle''. - Parameter actionName: The name of the undo action. - Returns: The localized title of the undo menu item. * @param action_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -163,31 +162,31 @@ namespace cocoon void undo_nested_group() const; /** * @brief Returns the `canRedo` property of `NSUndoManager`. - * @details A Boolean value that indicates whether the manager has any actions to redo. Because any undo operation registered clears the redo stack, this method posts an NSUndoManagerCheckpointNotification to allow clients to apply their pending operations before testing the redo stack. + * @details Whether the receiver has any actions to redo. Because any undo operation registered clears the redo stack, this method posts an NSUndoManagerCheckpointNotification to allow clients to apply their pending operations before testing the redo stack. * @return The converted Objective-C result. */ bool can_redo() const; /** * @brief Returns the `canUndo` property of `NSUndoManager`. - * @details A Boolean value that indicates whether the manager has any actions to undo. The return value does not mean you can safely invoke ''undo'' or ''undoNestedGroup'' — you may have to close open undo groups first. + * @details Whether the receiver has any actions to undo. The return value does not mean you can safely invoke ''undo'' or ''undoNestedGroup'' — you may have to close open undo groups first. * @return The converted Objective-C result. */ bool can_undo() const; /** * @brief Returns the `groupingLevel` property of `NSUndoManager`. - * @details The number of nested undo groups (or redo groups, if redo is the most recent operation) in the current event loop. An integer indicating the number of nested groups. If '0' is returned, there is no open undo or redo group. + * @details The number of nested undo groups (or redo groups, if Redo was invoked last) in the current event loop. An integer indicating the number of nested groups. If '0' is returned, there is no open undo or redo group. * @return The converted Objective-C result. */ std::int64_t grouping_level() const; /** * @brief Returns the `groupsByEvent` property of `NSUndoManager`. - * @details A Boolean value that indicates whether the manager automatically creates undo groups around each pass of the run loop. If 'true', the receiver automatically creates undo groups around each pass of the run loop. The default is 'true'. If you turn automatic grouping off, you must close groups explicitly before invoking either ''undo'' or ''undoNestedGroup''. + * @details A Boolean value that indicates whether the receiver automatically creates undo groups around each pass of the run loop. If 'true', the receiver automatically creates undo groups around each pass of the run loop. The default is 'true'. If you turn automatic grouping off, you must close groups explicitly before invoking either ''undo'' or ''undoNestedGroup''. * @return The converted Objective-C result. */ bool groups_by_event() const; /** * @brief Sets the `groupsByEvent` property of `NSUndoManager`. - * @details A Boolean value that indicates whether the manager automatically creates undo groups around each pass of the run loop. If 'true', the receiver automatically creates undo groups around each pass of the run loop. The default is 'true'. If you turn automatic grouping off, you must close groups explicitly before invoking either ''undo'' or ''undoNestedGroup''. + * @details A Boolean value that indicates whether the receiver automatically creates undo groups around each pass of the run loop. If 'true', the receiver automatically creates undo groups around each pass of the run loop. The default is 'true'. If you turn automatic grouping off, you must close groups explicitly before invoking either ''undo'' or ''undoNestedGroup''. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_groups_by_event(bool value) const; @@ -217,19 +216,19 @@ namespace cocoon std::string redo_action_name() const; /** * @brief Returns the `redoCount` property of `NSUndoManager`. - * @details The number of times you can invoke redo before there are no actions left to redo. + * @details How many times 'redo' can be invoked before there are no more actions left to be redone * @return The converted Objective-C result. */ std::uint64_t redo_count() const; /** * @brief Returns the `redoMenuItemTitle` property of `NSUndoManager`. - * @details The title of the Redo menu command, such as Redo Paste. Returns “Redo” if no action name has been assigned or nil if there is nothing to redo. + * @details The complete title of the Redo menu command, for example, “Redo Paste.” Returns “Redo” if no action name has been assigned or nil if there is nothing to redo. * @return The converted Objective-C result. */ std::string redo_menu_item_title() const; /** * @brief Returns the `redoing` property of `NSUndoManager`. - * @details Returns a Boolean value that indicates whether the manager is in the process of performing a redo action. + * @details Whether the receiver is in the process of performing its ''redo'' method. * @return The converted Objective-C result. */ bool is_redoing() const; @@ -259,25 +258,25 @@ namespace cocoon std::string undo_action_name() const; /** * @brief Returns the `undoCount` property of `NSUndoManager`. - * @details The number of times you can invoke undo before there are no actions left to undo. A nonzero value doesn't imply you can safely invoke ''undo'' immediately, because you may have to close open undo groups first. + * @details How many times 'undo' can be invoked before there are no more actions left to be undone * @return The converted Objective-C result. */ std::uint64_t undo_count() const; /** * @brief Returns the `undoMenuItemTitle` property of `NSUndoManager`. - * @details The title of the Undo menu command, such as Undo Paste. Returns “Undo” if no action name has been assigned or nil if there is nothing to undo. + * @details The complete title of the Undo menu command, for example, “Undo Paste.” Returns “Undo” if no action name has been assigned or nil if there is nothing to undo. * @return The converted Objective-C result. */ std::string undo_menu_item_title() const; /** * @brief Returns the `undoRegistrationEnabled` property of `NSUndoManager`. - * @details A Boolean value that indicates whether the recording of undo operations is enabled. + * @details Whether the recording of undo operations is enabled. * @return The converted Objective-C result. */ bool is_undo_registration_enabled() const; /** * @brief Returns the `undoing` property of `NSUndoManager`. - * @details Returns a Boolean value that indicates whether the manager is in the process of performing an undo action. + * @details Whether the receiver is in the process of performing its ''undo'' or ''undoNestedGroup'' method. * @return The converted Objective-C result. */ bool is_undoing() const; diff --git a/include/generated/unique_id_specifier.h b/include/generated/unique_id_specifier.h index d78875ac..6bb33181 100644 --- a/include/generated/unique_id_specifier.h +++ b/include/generated/unique_id_specifier.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUniqueIDSpecifier` (Foundation). - * @details A specifier for an object in a collection (or container) by unique ID. This specifier works only for objects that have an ID property. The unique ID object passed to an instance of 'NSUniqueIDSpecifier' must be either an 'NSNumber' object or an 'NSString' object. The exact type should match the scripting dictionary declaration of the ID attribute for the relevant scripting class. You can expect that the ID property will be read only for any object that supports it. Therefore a scripter can obtain the unique ID for an object and refer to the object by the ID, but cannot set the unique ID. You don't normally subclass 'NSUniqueIDSpecifier'. The evaluation of 'NSUniqueIDSpecifier' objects follows these steps until the specified object is found: 1. If the container implements a method whose selector matches the relevant 'valueIn\WithUniqueID:' pattern established by scripting key-value coding, the method is invoked. This method can potentially be very fast, and it may be relatively easy to implement. 2. As is the case when evaluating any script object specifier, the container of the specified object is given a chance to evaluate the object specifier. If the container class implements the \ method, the method is invoked. This method can potentially be very fast, but it is relatively difficult to implement. 3. An ''NSWhoseSpecifier'' object that specifies the first object whose relevant ''ID '' attribute matches the ID is synthesized and evaluated. The 'NSWhoseSpecifier' object must search through all of the keyed elements in the container, looking for a match. The search is potentially very slow. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptObjectSpecifier. * @@ -38,13 +37,11 @@ namespace cocoon explicit UniqueIDSpecifier(Adopt adopt); /** * @brief Returns the `uniqueID` property of `NSUniqueIDSpecifier`. - * @details The unique ID of the object to be located. * @return The converted Objective-C result. */ Object unique_id() const; /** * @brief Sets the `uniqueID` property of `NSUniqueIDSpecifier`. - * @details The unique ID of the object to be located. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_unique_id(const Object& value) const; diff --git a/include/generated/unit.h b/include/generated/unit.h index 2e851acb..b076ac55 100644 --- a/include/generated/unit.h +++ b/include/generated/unit.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnit` (Foundation). - * @details An abstract class representing a unit of measure. Each instance of an ''Unit'' subclass consists of a ''symbol'', which can be used to create string representations of ''NSMeasurement'' objects with the ''MeasurementFormatter'' class. The ''Dimension'' subclass is an abstract class that represents a dimensional unit, which can be converted into different units of the same type. The Foundation framework provides several concrete ''Dimension'' subclasses to represent the most common physical quantities, including mass, length, duration, and speed. \#\#\# Subclassing Notes ''NSUnit'' is intended for subclassing. For dimensional units, you should use one of the Apple provided ''Dimension'' subclasses listed in Table 1 of ''Dimension'', or create a custom subclass of ''Dimension''. You can create a direct subclass of ''NSUnit'' to represent a custom dimensionless unit, such as a count, score, or ratio. + * @details NSUnit is the base class for all unit types (dimensional and dimensionless). * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -33,7 +33,6 @@ namespace cocoon explicit Unit(Adopt adopt); /** * @brief Returns the `symbol` property of `NSUnit`. - * @details The symbolic representation of the unit. The symbol of a unit is a string that can be used to designate a number as a quantity of a particular unit in user-readable representations. Units typically have symbols that are abbreviated and standardized, so as to be easily and unambiguously conveyed. For example, the 'milePerHour' unit has the symbol 'mph'. If a unit does not have a standardized or well-understood symbol, the lowercase name of the unit can be used. For example, the 'metricCup' unit has the symbol 'metric cup'. Unit symbols may incorporate a metric prefix to indicate a multiple or fraction of existing unit symbols. For example, the 'kilogram' unit has the symbol 'kg', which uses the SI prefix k for kilo- to indicate a magnitude of 10^3 for the 'gram' unit, and the 'microgram' unit has the symbol 'µg', which uses the SI prefix µ for micro- to indicate a magnitude of 10^-6 for the 'gram' unit. * @return The converted Objective-C result. */ std::string symbol() const; diff --git a/include/generated/unit_acceleration.h b/include/generated/unit_acceleration.h index 7fd3f527..e9fbd465 100644 --- a/include/generated/unit_acceleration.h +++ b/include/generated/unit_acceleration.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitAcceleration` (Foundation). - * @details A unit of measure for acceleration. You typically use instances of ''NSUnitAcceleration'' to represent specific quantities of acceleration using the ''NSMeasurement'' class. \#\#\# Acceleration Acceleration is the rate of change of velocity. Acceleration can be expressed by SI derived units in terms of meters per second squared (m/s2). The ''NSUnitAcceleration'' class defines its ''Dimension/baseUnit()'' as ''metersPerSecondSquared'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Meters Per Second Squared | ''metersPerSecondSquared'' | m/s² | '1.0' | | Gravity | ''gravity'' | g | '9.81' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,13 +31,12 @@ namespace cocoon explicit UnitAcceleration(Adopt adopt); /** * @brief Returns the `gravity` property of `NSUnitAcceleration`. - * @details The gravity unit of acceleration. * @return The converted Objective-C result. */ static UnitAcceleration gravity(); /** * @brief Returns the `metersPerSecondSquared` property of `NSUnitAcceleration`. - * @details The meters per second squared unit of acceleration. + * @details Base unit - metersPerSecondSquared * @return The converted Objective-C result. */ static UnitAcceleration meters_per_second_squared(); diff --git a/include/generated/unit_angle.h b/include/generated/unit_angle.h index 8f7abd66..e2f0d15c 100644 --- a/include/generated/unit_angle.h +++ b/include/generated/unit_angle.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitAngle` (Foundation). - * @details A unit of measure for planar angle and rotation. You typically use instances of ''NSUnitAngle'' to represent specific quantities of planar angle using the ''NSMeasurement'' class. \#\#\# Angle Angle is a quantity of rotation. The SI unit for angle is the radian (rad), which is dimensionless and defined to be the angle subtended by an arc that is equal in length to the radius of a circle. Angle is also commonly expressed in terms of degrees (°) and revolutions (rev). The ''NSUnitAngle'' class defines its ''Dimension/baseUnit()'' as ''degrees'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Definition | |---|---|---|---| | Degrees | ''degrees'' | ° | '1.0' | | Arc Minutes | ''arcMinutes'' | ʹ | '0.016667' | | Arc Seconds | ''arcSeconds'' | ʺ | '0.00027778' | | Radians | ''radians'' | rad | '57.2958' | | Gradians | ''gradians'' | grad | '0.9' | | Revolutions | ''revolutions'' | rev | '360' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,37 +31,32 @@ namespace cocoon explicit UnitAngle(Adopt adopt); /** * @brief Returns the `arcMinutes` property of `NSUnitAngle`. - * @details The arc minutes unit of angle. * @return The converted Objective-C result. */ static UnitAngle arc_minutes(); /** * @brief Returns the `arcSeconds` property of `NSUnitAngle`. - * @details The arc seconds unit of angle. * @return The converted Objective-C result. */ static UnitAngle arc_seconds(); /** * @brief Returns the `degrees` property of `NSUnitAngle`. - * @details The degrees unit of angle. + * @details Base unit - degrees * @return The converted Objective-C result. */ static UnitAngle degrees(); /** * @brief Returns the `gradians` property of `NSUnitAngle`. - * @details The gradians unit of angle. * @return The converted Objective-C result. */ static UnitAngle gradians(); /** * @brief Returns the `radians` property of `NSUnitAngle`. - * @details The radians unit of angle. * @return The converted Objective-C result. */ static UnitAngle radians(); /** * @brief Returns the `revolutions` property of `NSUnitAngle`. - * @details The revolutions unit of angle. * @return The converted Objective-C result. */ static UnitAngle revolutions(); diff --git a/include/generated/unit_area.h b/include/generated/unit_area.h index 851b6962..567cadea 100644 --- a/include/generated/unit_area.h +++ b/include/generated/unit_area.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitArea` (Foundation). - * @details A unit of measure for area. You typically use instances of ''NSUnitArea'' to represent specific quantities of area using the ''NSMeasurement'' class. \#\#\# Area Area is a quantity of extent in two dimensions. Area can be expressed by SI derived units in terms of square meters (m2). Area is also commonly measured in square feet (ft2) and acres (ac). The ''NSUnitArea'' class defines its ''Dimension/baseUnit()'' as ''squareMeters'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Square Megameters | ''squareMegameters'' | Mm² | '1e12' | | Square Kilometers | ''squareKilometers'' | km² | '1000000.0' | | Square Meters | ''squareMeters'' | m² | '1.0' | | Square Centimeter | ''squareCentimeters'' | cm² | '0.0001' | | Square Millimeters | ''squareMillimeters'' | mm² | '0.000001' | | Square Micrometers | ''squareMicrometers'' | µm² | '1e-12' | | Square Nanometers | ''squareNanometers'' | nm² | '1e-18' | | Square Inches | ''squareInches'' | in² | '0.00064516' | | Square Feet | ''squareFeet'' | ft² | '0.092903' | | Square Yards | ''squareYards'' | yd² | '0.836127' | | Square Miles | ''squareMiles'' | mi² | '2.59e+6' | | Acres | ''acres'' | ac | '4046.86' | | Ares | ''ares'' | a | '100' | | Hectares | ''hectares'' | ha | '10000' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,85 +31,72 @@ namespace cocoon explicit UnitArea(Adopt adopt); /** * @brief Returns the `acres` property of `NSUnitArea`. - * @details The acres unit of area. * @return The converted Objective-C result. */ static UnitArea acres(); /** * @brief Returns the `ares` property of `NSUnitArea`. - * @details The ares unit of area. * @return The converted Objective-C result. */ static UnitArea ares(); /** * @brief Returns the `hectares` property of `NSUnitArea`. - * @details The hectares unit of area. * @return The converted Objective-C result. */ static UnitArea hectares(); /** * @brief Returns the `squareCentimeters` property of `NSUnitArea`. - * @details The square centimeters unit of area. * @return The converted Objective-C result. */ static UnitArea square_centimeters(); /** * @brief Returns the `squareFeet` property of `NSUnitArea`. - * @details The square feet unit of area. * @return The converted Objective-C result. */ static UnitArea square_feet(); /** * @brief Returns the `squareInches` property of `NSUnitArea`. - * @details The square inches unit of area. * @return The converted Objective-C result. */ static UnitArea square_inches(); /** * @brief Returns the `squareKilometers` property of `NSUnitArea`. - * @details The square kilometers unit of area. * @return The converted Objective-C result. */ static UnitArea square_kilometers(); /** * @brief Returns the `squareMegameters` property of `NSUnitArea`. - * @details The square megameters unit of area. + * @details Base unit - squareMeters * @return The converted Objective-C result. */ static UnitArea square_megameters(); /** * @brief Returns the `squareMeters` property of `NSUnitArea`. - * @details The square meters unit of area. * @return The converted Objective-C result. */ static UnitArea square_meters(); /** * @brief Returns the `squareMicrometers` property of `NSUnitArea`. - * @details The square micrometers unit of area. * @return The converted Objective-C result. */ static UnitArea square_micrometers(); /** * @brief Returns the `squareMiles` property of `NSUnitArea`. - * @details The square miles unit of area. * @return The converted Objective-C result. */ static UnitArea square_miles(); /** * @brief Returns the `squareMillimeters` property of `NSUnitArea`. - * @details The square millimeters unit of area. * @return The converted Objective-C result. */ static UnitArea square_millimeters(); /** * @brief Returns the `squareNanometers` property of `NSUnitArea`. - * @details The square nanometers unit of area. * @return The converted Objective-C result. */ static UnitArea square_nanometers(); /** * @brief Returns the `squareYards` property of `NSUnitArea`. - * @details The square yards unit of area. * @return The converted Objective-C result. */ static UnitArea square_yards(); diff --git a/include/generated/unit_concentration_mass.h b/include/generated/unit_concentration_mass.h index 35ecb8d7..f9d1e8a6 100644 --- a/include/generated/unit_concentration_mass.h +++ b/include/generated/unit_concentration_mass.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitConcentrationMass` (Foundation). - * @details A unit of measure for concentration of mass. You typically use instances of ''NSUnitConcentrationMass'' to represent specific quantities of concentration using the ''NSMeasurement'' class. \#\#\# Concentration of Mass Concentration is the abundance of a constituent within a volume. Concentration can be expressed by SI derived units in terms of kilograms per cubic meter (kg/m3). The ''NSUnitConcentrationMass'' class defines its ''Dimension/baseUnit()'' as ''gramsPerLiter'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Grams Per Liter | ''gramsPerLiter'' | g/L | '1' | | Milligrams Per Deciliter | ''milligramsPerDeciliter'' | mg/dL | '0.01' | | Millimoles Per Liter | ''millimolesPerLiter(withGramsPerMole:)'' | mmol/L | '18 gramsPerMole' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -39,20 +38,18 @@ namespace cocoon explicit UnitConcentrationMass(Adopt adopt); /** * @brief Calls `+[NSUnitConcentrationMass millimolesPerLiterWithGramsPerMole:]`. - * @details Returns the millimoles per liter unit with the specified grams per mole. * @param grams_per_mole Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static UnitConcentrationMass millimoles_per_liter_with_grams_per_mole(double grams_per_mole); /** * @brief Returns the `gramsPerLiter` property of `NSUnitConcentrationMass`. - * @details The grams per liter unit of concentration. + * @details Base unit - gramsPerLiter * @return The converted Objective-C result. */ static UnitConcentrationMass grams_per_liter(); /** * @brief Returns the `milligramsPerDeciliter` property of `NSUnitConcentrationMass`. - * @details The milligrams per deciliter unit of concentration. * @return The converted Objective-C result. */ static UnitConcentrationMass milligrams_per_deciliter(); diff --git a/include/generated/unit_converter.h b/include/generated/unit_converter.h index e6f75bd2..801c169c 100644 --- a/include/generated/unit_converter.h +++ b/include/generated/unit_converter.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitConverter` (Foundation). - * @details An abstract class that provides a description of how to convert a unit to and from the base unit of its dimension. For units that can be converted by a scale factor or linear equation, use the concrete subclass ''UnitConverterLinear''. \#\#\# Subclassing Notes ''NSUnitConverter'' is an abstract class that is intended for subclassing. You can implement your own subclass of ''NSUnitConverter'' to convert between units according to any desired mapping function. For example, units may be converted using a logarithmic, exponential, or quantile scale. \#\#\#\# Methods to Override All subclasses must fully implement the following methods: - ''baseUnitValue(fromValue:)'' - ''value(fromBaseUnitValue:)'' \#\#\#\# Alternatives to Subclassing As stated above, most physical units can be converted using a linear equation with ''UnitConverterLinear''. You should only create a custom subclass of ''NSUnitConverter'' for units that cannot be converted in this way. + * @details NSUnitConverter describes how to convert a unit to and from the base unit of its dimension. Subclass NSUnitConverter to implement new ways of converting a unit. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -40,14 +40,14 @@ namespace cocoon explicit UnitConverter(Adopt adopt); /** * @brief Calls `-[NSUnitConverter baseUnitValueFromValue:]`. - * @details For a given unit, returns the specified value of that unit in terms of the base unit of its dimension. This method takes a value in a particular unit and returns the result of converting it into the base unit of that unit's dimension. For example, a converter for the miles unit calling this method, passing '1.0' to the 'value' parameter, results in '1609.34' (1 mi = 1609.34 m). \@param value Value in terms of the unit class. \@return Value in terms of the base unit. + * @details This method takes a value in terms of a unit and returns the corresponding value in terms of the base unit of the original unit's dimension. \@param value Value in terms of the unit class \@return Value in terms of the base unit * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double base_unit_value_from_value(double value) const; /** * @brief Calls `-[NSUnitConverter valueFromBaseUnitValue:]`. - * @details For a given unit, returns the specified base unit value in terms of that unit. This method takes in a value in terms of the base unit of a unit's dimension and returns the equivalent value in terms of the unit. \@param baseUnitValue Value in terms of the base unit. \@return Value in terms of the unit class. + * @details This method takes in a value in terms of the base unit of a unit's dimension and returns the equivalent value in terms of the unit. \@param baseUnitValue Value in terms of the base unit \@return Value in terms of the unit class * @param base_unit_value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ diff --git a/include/generated/unit_converter_linear.h b/include/generated/unit_converter_linear.h index cdc4eae0..7e5b97e4 100644 --- a/include/generated/unit_converter_linear.h +++ b/include/generated/unit_converter_linear.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitConverterLinear` (Foundation). - * @details A description of how to convert between units using a linear equation. A linear equation for unit conversion takes the form 'y = mx + b', such that the following is true: - 'y' is the value in terms of the base unit of the dimension. - 'm' is the known coefficient to use for this unit's conversion. - 'x' is the value in terms of the unit on which you call this method. - 'b' is the known constant to use for this unit's conversion. The 'baseUnitValueFromValue:' method performs the conversion in the form of 'y = mx + b', where 'x' represents the value passed in and 'y' represents the value returned. The 'valueFromBaseUnitValue:' method performs the inverse conversion in the form of 'x = (y - b) / m', where 'y' represents the value passed in and 'x' represents the value returned. For example, consider the ''UnitTemperature/fahrenheit'' unit that ''UnitTemperature'' defines. The ''UnitConverter/baseUnitValue(fromValue:)'' method calculates the value in the base unit, ''UnitTemperature/kelvin'', using the formula 'K = (0.55555555555556) × °F + 255.37222222222427'. The ''UnitConverter/value(fromBaseUnitValue:)'' method calculates the value in ''UnitTemperature/fahrenheit'' using the formula '°F = (K — 255.37222222222427) / (0.55555555555556)', where the ''coefficient'' is '(0.55555555555556)' and the ''constant'' is '255.37222222222427'. \@TabNavigator { \@Tab("Swift") { '''swift let kelvinToFahrenheit = UnitConverterLinear(coefficient: 0.55555555555556, constant: 255.37222222222427) ''' } \@Tab("Objective-C") { '''objc NSUnitConverter kelvinToFahrenheit = [[NSUnitConverterLinear alloc] initWithCoefficient:0.55555555555556 constant:255.37222222222427]; ''' } } Units that perform conversion using only a scale factor have a ''coefficient'' equal to the scale factor and a ''constant'' equal to '0'. For example, consider the ''UnitLength/kilometers'' unit ''UnitLength'' defines. The ''UnitConverter/baseUnitValue(fromValue:)'' method calculates the value in meters using the formula 'valueInMeters = 1000 valueInKilometers + 0'. The ''UnitConverter/value(fromBaseUnitValue:)'' calculates the value in kilometers using the formula 'valueInKilometers = (valueInMeters - 0) / 1000', where the coefficient is '1000' and the constant is '0'. \@TabNavigator { \@Tab("Swift") { '''swift let kilometersToMeters = UnitConverterLinear(coefficient: 1000.0, constant: 0.0) ''' } \@Tab("Objective-C") { '''objc NSUnitConverterLinear kilometersToMeters = [[NSUnitConverterLinear alloc] initWithCoefficient:1000.0 constant:0.0]; ''' } } * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref UnitConverter. * @@ -37,13 +36,12 @@ namespace cocoon explicit UnitConverterLinear(Adopt adopt); /** * @brief Returns the `coefficient` property of `NSUnitConverterLinear`. - * @details The coefficient to use in the linear unit conversion calculation. + * @details For units that require linear conversion, the methods perform calculations in the form of y = ax + b, where - x is the value in terms of the unit on which this method is called - y is the value in terms of the base unit of the dimension - a is the known coefficient used for this unit's conversion - b is the known constant used for this unit's conversion baseUnitValueFromValue: performs the conversion in the form of y = ax + b, where x represents the value passed in and y represents the value returned. valueFromBaseUnitValue: performs the inverse conversion in the form of x = (y + (-1 b))/a, where y represents the value passed in and x represents the value returned. An example of this is NSUnitTemperature. For Celsius, baseUnitValueFromValue: calculates the value in Kelvin using the formula K = 1 °C + 273.15 and valueFromBaseUnitValue: calculates the value in Celsius using the formula C° = (K + (-1 273.15))/1 where the coefficient is 1 and the constant is 273.15. For units that only require conversion by scale factor, the coefficient is the scale factor and the constant is always 0. baseUnitValueFromValue: calculates the value in meters using the formula valueInMeters = 1000 valueInKilometers + 0 and valueFromBaseUnitValue: calculates the value in kilometers using the formula valueInKilometers = valueInMeters / 1000 where the coefficient is 1000 and the constant is 0. This API provides a convenience initializer initWithCoefficient: that assumes the constant is 0. * @return The converted Objective-C result. */ double coefficient() const; /** * @brief Returns the `constant` property of `NSUnitConverterLinear`. - * @details The constant to use in the linear unit conversion calculation. * @return The converted Objective-C result. */ double constant() const; diff --git a/include/generated/unit_dispersion.h b/include/generated/unit_dispersion.h index ca6a3c7e..f5dee4eb 100644 --- a/include/generated/unit_dispersion.h +++ b/include/generated/unit_dispersion.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitDispersion` (Foundation). - * @details A unit of measure for specific quantities of dispersion. You typically use instances of ''NSUnitDispersion'' to represent specific quantities of dispersion using the ''NSMeasurement'' class. \#\#\# Dispersion Dispersion describes the amount of a constituent divided by the amount of all other constituents in a mixture. Dispersion is a dimensionless quantity that is commonly expressed in "parts-per" notation, such as "parts per million" (ppm), to describe small relative quantities. The ''NSUnitDispersion'' class defines its ''Dimension/baseUnit()'' as ''partsPerMillion''. | Name | Method | Abbreviation | |---|---|---| | Parts Per Million | ''partsPerMillion'' | ppm | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,7 +31,7 @@ namespace cocoon explicit UnitDispersion(Adopt adopt); /** * @brief Returns the `partsPerMillion` property of `NSUnitDispersion`. - * @details The parts per million unit of dispersion. + * @details Base unit - partsPerMillion * @return The converted Objective-C result. */ static UnitDispersion parts_per_million(); diff --git a/include/generated/unit_duration.h b/include/generated/unit_duration.h index 120ffe36..5eea3ab2 100644 --- a/include/generated/unit_duration.h +++ b/include/generated/unit_duration.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitDuration` (Foundation). - * @details A unit of measure for a duration of time. You typically use instances of ''NSUnitDuration'' to represent specific quantities of planar angle using the ''NSMeasurement'' class. \#\#\# Duration Duration is a quantity of time. The SI unit for time is the second (sec), which is defined in terms of the radioactivity of a cesium-133 atom. Duration is also commonly expressed in terms of minutes (min) and hours (hr). > Note: > Use the ''NSDateComponents'' class to represent quantities of calendrical units, such as days, weeks, months, and years. The ''NSUnitDuration'' class defines its ''Dimension/baseUnit()'' as ''seconds'', and provides the following units, which ''UnitConverterLinear'' converters initialize with the given coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Seconds | ''seconds'' | sec | '1' | | Minutes | ''minutes'' | min | '60' | | Hours | ''hours'' | hr | '3600' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,43 +31,37 @@ namespace cocoon explicit UnitDuration(Adopt adopt); /** * @brief Returns the `hours` property of `NSUnitDuration`. - * @details The hours unit of duration. + * @details Base unit - seconds * @return The converted Objective-C result. */ static UnitDuration hours(); /** * @brief Returns the `microseconds` property of `NSUnitDuration`. - * @details The microseconds unit of duration. * @return The converted Objective-C result. */ static UnitDuration microseconds(); /** * @brief Returns the `milliseconds` property of `NSUnitDuration`. - * @details The milliseconds unit of duration. * @return The converted Objective-C result. */ static UnitDuration milliseconds(); /** * @brief Returns the `minutes` property of `NSUnitDuration`. - * @details The minutes unit of duration. * @return The converted Objective-C result. */ static UnitDuration minutes(); /** * @brief Returns the `nanoseconds` property of `NSUnitDuration`. - * @details The nanoseconds unit of duration. * @return The converted Objective-C result. */ static UnitDuration nanoseconds(); /** * @brief Returns the `picoseconds` property of `NSUnitDuration`. - * @details The picoseconds unit of duration. * @return The converted Objective-C result. */ static UnitDuration picoseconds(); /** * @brief Returns the `seconds` property of `NSUnitDuration`. - * @details The seconds unit of duration. * @return The converted Objective-C result. */ static UnitDuration seconds(); diff --git a/include/generated/unit_electric_charge.h b/include/generated/unit_electric_charge.h index e5b2c5e5..a81e5c63 100644 --- a/include/generated/unit_electric_charge.h +++ b/include/generated/unit_electric_charge.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitElectricCharge` (Foundation). - * @details A unit of measure for electric charge. You typically use instances of ''NSUnitElectricCharge'' to represent specific quantities of electric charge using the ''NSMeasurement'' class. \#\#\# Electric Charge Electric charge is a fundamental physical property of matter that causes it to experience a force within an electromagnetic field. The SI unit for electric charge is the coulomb (C), which is defined as the amount of charge carried by a current of one ampere in one second (1C = 1A · 1s). Charge is also commonly expressed in terms of ampere hours (Ah). The ''NSUnitElectricCharge'' class defines its ''Dimension/baseUnit()'' as ''coulombs'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Coulombs | ''coulombs'' | C | '1.0' | | Megaampere Hours | ''megaampereHours'' | MAh | '3.6e9' | | Kiloampere Hours | ''kiloampereHours'' | kAh | '3600000.0' | | Ampere Hours | ''ampereHours'' | Ah | '3600.0' | | Milliampere Hours | ''milliampereHours'' | mAh | '3.6' | | Microampere Hours | ''microampereHours'' | µAh | '0.0036' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,37 +31,32 @@ namespace cocoon explicit UnitElectricCharge(Adopt adopt); /** * @brief Returns the `ampereHours` property of `NSUnitElectricCharge`. - * @details The ampere hours unit of electric charge. * @return The converted Objective-C result. */ static UnitElectricCharge ampere_hours(); /** * @brief Returns the `coulombs` property of `NSUnitElectricCharge`. - * @details The coulombs unit of electric charge. + * @details Base unit - coulombs * @return The converted Objective-C result. */ static UnitElectricCharge coulombs(); /** * @brief Returns the `kiloampereHours` property of `NSUnitElectricCharge`. - * @details The kiloampere hours unit of electric charge. * @return The converted Objective-C result. */ static UnitElectricCharge kiloampere_hours(); /** * @brief Returns the `megaampereHours` property of `NSUnitElectricCharge`. - * @details The megaampere hours unit of electric charge. * @return The converted Objective-C result. */ static UnitElectricCharge megaampere_hours(); /** * @brief Returns the `microampereHours` property of `NSUnitElectricCharge`. - * @details The microampere hours unit of electric charge. * @return The converted Objective-C result. */ static UnitElectricCharge microampere_hours(); /** * @brief Returns the `milliampereHours` property of `NSUnitElectricCharge`. - * @details The milliampere hours unit of electric charge. * @return The converted Objective-C result. */ static UnitElectricCharge milliampere_hours(); diff --git a/include/generated/unit_electric_current.h b/include/generated/unit_electric_current.h index 845138bf..9f745c00 100644 --- a/include/generated/unit_electric_current.h +++ b/include/generated/unit_electric_current.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitElectricCurrent` (Foundation). - * @details A unit of measure for electric current. You typically use instances of ''NSUnitElectricCurrent'' to represent specific quantities of electric current using the ''NSMeasurement'' class. \#\#\# Electric Current Electric current is the flow of electric charge. The SI unit for electric current is the ampere (A), which is defined in terms the production of electromagnetic force between two parallel linear conductors. It can also be expressed as the flow of one coulomb per second (1A = 1C / s). The ''NSUnitElectricCurrent'' class defines its ''Dimension/baseUnit()'' as ''amperes'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Megaamperes | ''megaamperes'' | MA | '1000000.0' | | Kiloamperes | ''kiloamperes'' | kA | '1000.0' | | Amperes | ''amperes'' | A | '1.0' | | Milliamperes | ''milliamperes'' | mA | '0.001' | | Microamperes | ''microamperes'' | µA | '0.000001' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,31 +31,27 @@ namespace cocoon explicit UnitElectricCurrent(Adopt adopt); /** * @brief Returns the `amperes` property of `NSUnitElectricCurrent`. - * @details The amperes unit of electric current. * @return The converted Objective-C result. */ static UnitElectricCurrent amperes(); /** * @brief Returns the `kiloamperes` property of `NSUnitElectricCurrent`. - * @details The kiloamperes unit of electric current. * @return The converted Objective-C result. */ static UnitElectricCurrent kiloamperes(); /** * @brief Returns the `megaamperes` property of `NSUnitElectricCurrent`. - * @details The megaamperes unit of electric current. + * @details Base unit - amperes * @return The converted Objective-C result. */ static UnitElectricCurrent megaamperes(); /** * @brief Returns the `microamperes` property of `NSUnitElectricCurrent`. - * @details The microamperes unit of electric current. * @return The converted Objective-C result. */ static UnitElectricCurrent microamperes(); /** * @brief Returns the `milliamperes` property of `NSUnitElectricCurrent`. - * @details The milliamperes unit of electric current. * @return The converted Objective-C result. */ static UnitElectricCurrent milliamperes(); diff --git a/include/generated/unit_electric_potential_difference.h b/include/generated/unit_electric_potential_difference.h index d0c4535e..684fe5a6 100644 --- a/include/generated/unit_electric_potential_difference.h +++ b/include/generated/unit_electric_potential_difference.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitElectricPotentialDifference` (Foundation). - * @details A unit of measure for electric potential difference. You typically use instances of ''NSUnitElectricPotentialDifference'' to represent specific quantities of electric potential difference using the ''NSMeasurement'' class. \#\#\# Electric Potential Difference Electric potential difference is the amount of electric potential energy of a point charge at a point in space. The SI unit for electric potential difference is the volt (V), which is derived as the difference in electric potential energy between two points of a linear conductor when an electric current of one ampere dissipates one watt of power between those points (1V = 1W/1A). The ''NSUnitElectricPotentialDifference'' class defines its ''Dimension/baseUnit()'' as ''volts'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Megavolts | ''megavolts'' | MV | '1000000.0' | | Kilovolts | ''kilovolts'' | kV | '1000.0' | | Volts | ''volts'' | V | '1.0' | | Millivolts | ''millivolts'' | mV | '0.001' | | Microvolts | ''microvolts'' | µV | '0.000001' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,31 +31,27 @@ namespace cocoon explicit UnitElectricPotentialDifference(Adopt adopt); /** * @brief Returns the `kilovolts` property of `NSUnitElectricPotentialDifference`. - * @details The kilovolts unit of electric potential difference. * @return The converted Objective-C result. */ static UnitElectricPotentialDifference kilovolts(); /** * @brief Returns the `megavolts` property of `NSUnitElectricPotentialDifference`. - * @details The megavolts unit of electric potential difference. + * @details Base unit - volts * @return The converted Objective-C result. */ static UnitElectricPotentialDifference megavolts(); /** * @brief Returns the `microvolts` property of `NSUnitElectricPotentialDifference`. - * @details The microvolts unit of electric potential difference. * @return The converted Objective-C result. */ static UnitElectricPotentialDifference microvolts(); /** * @brief Returns the `millivolts` property of `NSUnitElectricPotentialDifference`. - * @details The millivolts unit of electric potential difference. * @return The converted Objective-C result. */ static UnitElectricPotentialDifference millivolts(); /** * @brief Returns the `volts` property of `NSUnitElectricPotentialDifference`. - * @details The volts unit of electric potential difference. * @return The converted Objective-C result. */ static UnitElectricPotentialDifference volts(); diff --git a/include/generated/unit_electric_resistance.h b/include/generated/unit_electric_resistance.h index 1adb3233..bd9798e7 100644 --- a/include/generated/unit_electric_resistance.h +++ b/include/generated/unit_electric_resistance.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitElectricResistance` (Foundation). - * @details A unit of measure for electric resistance. You typically use instances of ''NSUnitElectricResistance'' to represent specific quantities of electric resistance using the ''NSMeasurement'' class. \#\#\# Electric Resistance Electric resistance is the difficulty of passing an electric current through a conductor. The SI unit for electric resistance is the ohm (Ω), which is derived as the electric resistance that produces one ampere of current between two points in conductor with one volt of electric potential difference (1Ω = 1V/1A). The ''NSUnitElectricResistance'' class defines its ''Dimension/baseUnit()'' as ''ohms'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Megaohms | ''megaohms'' | MΩ | '1000000.0' | | Kiloohms | ''kiloohms'' | kΩ | '1000.0' | | Ohms | ''ohms'' | Ω | '1.0' | | Milliohms | ''milliohms'' | mΩ | '0.001' | | Microohms | ''microohms'' | µΩ | '0.000001' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,31 +31,27 @@ namespace cocoon explicit UnitElectricResistance(Adopt adopt); /** * @brief Returns the `kiloohms` property of `NSUnitElectricResistance`. - * @details The kiloohms unit of electric resistance. * @return The converted Objective-C result. */ static UnitElectricResistance kiloohms(); /** * @brief Returns the `megaohms` property of `NSUnitElectricResistance`. - * @details The megaohms unit of electric resistance. + * @details Base unit - ohms * @return The converted Objective-C result. */ static UnitElectricResistance megaohms(); /** * @brief Returns the `microohms` property of `NSUnitElectricResistance`. - * @details The microohms unit of electric resistance. * @return The converted Objective-C result. */ static UnitElectricResistance microohms(); /** * @brief Returns the `milliohms` property of `NSUnitElectricResistance`. - * @details The milliohms unit of electric resistance. * @return The converted Objective-C result. */ static UnitElectricResistance milliohms(); /** * @brief Returns the `ohms` property of `NSUnitElectricResistance`. - * @details The ohms unit of electric resistance. * @return The converted Objective-C result. */ static UnitElectricResistance ohms(); diff --git a/include/generated/unit_energy.h b/include/generated/unit_energy.h index c197168c..01dbc0f3 100644 --- a/include/generated/unit_energy.h +++ b/include/generated/unit_energy.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitEnergy` (Foundation). - * @details A unit of measure for energy. You typically use instances of ''NSUnitEnergy'' to represent specific quantities of energy using the ''NSMeasurement'' class. \#\#\# Energy Energy is a fundamental property of matter than can be transferred and converted into different forms, such as kinetic, electric, and thermal. The SI unit for energy is the joule (J), which is derived as the work of one meter of displacement in the direction of a force of one newton (1J = 1N ∙ 1m). It can also be derived as the work required to displace an electric charge of one coulomb through an electrical potential difference of one volt (1J = 1C ∙ 1V), or the work required to produce one watt of power for one second (1J = 1W ∙ 1s). Energy is also commonly expressed in terms of the calorie (cal), or the energy needed to raise the temperature of one gram of water by one degree Celsius at a pressure of one atmosphere (1cal ≡ 4.184J). The ''NSUnitEnergy'' class defines its ''Dimension/baseUnit()'' as ''joules'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Kilojoules | ''kilojoules'' | kJ | '1000.0' | | Joules | ''joules'' | J | '1.0' | | Kilocalories | ''kilocalories'' | kCal | '4184.0' | | Calories | ''calories'' | cal | '4.184' | | Kilowatt Hours | ''kilowattHours'' | kWh | '3600000.0' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,31 +31,27 @@ namespace cocoon explicit UnitEnergy(Adopt adopt); /** * @brief Returns the `calories` property of `NSUnitEnergy`. - * @details The calories unit of energy. * @return The converted Objective-C result. */ static UnitEnergy calories(); /** * @brief Returns the `joules` property of `NSUnitEnergy`. - * @details The joules unit of energy. * @return The converted Objective-C result. */ static UnitEnergy joules(); /** * @brief Returns the `kilocalories` property of `NSUnitEnergy`. - * @details The kilocalories unit of energy. * @return The converted Objective-C result. */ static UnitEnergy kilocalories(); /** * @brief Returns the `kilojoules` property of `NSUnitEnergy`. - * @details The kilojoules unit of energy. + * @details Base unit - joules * @return The converted Objective-C result. */ static UnitEnergy kilojoules(); /** * @brief Returns the `kilowattHours` property of `NSUnitEnergy`. - * @details The kilowatt hours unit of energy. * @return The converted Objective-C result. */ static UnitEnergy kilowatt_hours(); diff --git a/include/generated/unit_frequency.h b/include/generated/unit_frequency.h index 63a2aca4..8b12e65f 100644 --- a/include/generated/unit_frequency.h +++ b/include/generated/unit_frequency.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitFrequency` (Foundation). - * @details A unit of measure for frequency. You typically use instances of ''NSUnitFrequency'' to represent specific quantities of frequency using the ''NSMeasurement'' class. \#\#\# Frequency Frequency is a quantity of occurrences for a repeating event over time. The SI unit for frequency is the hertz (Hz), which is a derived as one occurrence per second ('1 Hz = 1 / 1s'). The ''UnitFrequency'' class defines its ''Dimension/baseUnit()'' as ''hertz'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Terahertz | ''terahertz'' | THz | '1e12' | | Gigahertz | ''gigahertz'' | GHz | '1e9' | | Megahertz | ''megahertz'' | MHz | '1000000.0' | | Kilohertz | ''kilohertz'' | kHz | '1000.0' | | Hertz | ''hertz'' | Hz | '1' | | Millihertz | ''millihertz'' | mHz | '0.001' | | Microhertz | ''microhertz'' | µHz | '0.000001' | | Nanohertz | ''nanohertz'' | nHz | '1e-9' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -37,49 +36,42 @@ namespace cocoon static UnitFrequency frames_per_second(); /** * @brief Returns the `gigahertz` property of `NSUnitFrequency`. - * @details The gigahertz unit of frequency. * @return The converted Objective-C result. */ static UnitFrequency gigahertz(); /** * @brief Returns the `hertz` property of `NSUnitFrequency`. - * @details The hertz unit of frequency. * @return The converted Objective-C result. */ static UnitFrequency hertz(); /** * @brief Returns the `kilohertz` property of `NSUnitFrequency`. - * @details The kilohertz unit of frequency. * @return The converted Objective-C result. */ static UnitFrequency kilohertz(); /** * @brief Returns the `megahertz` property of `NSUnitFrequency`. - * @details The megahertz unit of frequency. * @return The converted Objective-C result. */ static UnitFrequency megahertz(); /** * @brief Returns the `microhertz` property of `NSUnitFrequency`. - * @details The microhertz unit of frequency. * @return The converted Objective-C result. */ static UnitFrequency microhertz(); /** * @brief Returns the `millihertz` property of `NSUnitFrequency`. - * @details The millihertz unit of frequency. * @return The converted Objective-C result. */ static UnitFrequency millihertz(); /** * @brief Returns the `nanohertz` property of `NSUnitFrequency`. - * @details The nanohertz unit of frequency. * @return The converted Objective-C result. */ static UnitFrequency nanohertz(); /** * @brief Returns the `terahertz` property of `NSUnitFrequency`. - * @details The terahertz unit of frequency. + * @details Base unit - hertz * @return The converted Objective-C result. */ static UnitFrequency terahertz(); diff --git a/include/generated/unit_fuel_efficiency.h b/include/generated/unit_fuel_efficiency.h index 704d7025..b390701f 100644 --- a/include/generated/unit_fuel_efficiency.h +++ b/include/generated/unit_fuel_efficiency.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitFuelEfficiency` (Foundation). - * @details A unit of measure for fuel efficiency. You typically use instances of ''NSUnitFuelEfficiency'' to represent specific quantities of fuel efficiency using the ''NSMeasurement'' class. \#\#\# Fuel Efficiency Fuel efficiency corresponds to the thermal efficiency of a process that converts the chemical potential energy of a fuel into kinetic energy. Fuel efficiency can be expressed by SI derived units in terms of cubic meters per meter (m3/m), but is more commonly expressed in terms of liters per kilometer (L/km) and miles per gallon (mpg). The ''NSUnitFuelEfficiency'' class defines its ''Dimension/baseUnit()'' as ''litersPer100Kilometers'', and provides the following units: | Name | Method | Symbol | |---|---|---| | Liters Per 100 Kilometers | ''litersPer100Kilometers'' | L/100km | | Miles Per Gallon | ''milesPerGallon'' | mpg | | Miles Per Imperial Gallon | ''milesPerImperialGallon'' | mpg | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,19 +31,17 @@ namespace cocoon explicit UnitFuelEfficiency(Adopt adopt); /** * @brief Returns the `litersPer100Kilometers` property of `NSUnitFuelEfficiency`. - * @details The liters per 100 kilometers unit of fuel efficiency. + * @details Base unit - litersPer100Kilometers * @return The converted Objective-C result. */ static UnitFuelEfficiency liters_per100_kilometers(); /** * @brief Returns the `milesPerGallon` property of `NSUnitFuelEfficiency`. - * @details The miles per gallon unit of fuel efficiency. * @return The converted Objective-C result. */ static UnitFuelEfficiency miles_per_gallon(); /** * @brief Returns the `milesPerImperialGallon` property of `NSUnitFuelEfficiency`. - * @details The miles per imperial gallon unit of fuel efficiency. * @return The converted Objective-C result. */ static UnitFuelEfficiency miles_per_imperial_gallon(); diff --git a/include/generated/unit_illuminance.h b/include/generated/unit_illuminance.h index c99b032c..d2bd3059 100644 --- a/include/generated/unit_illuminance.h +++ b/include/generated/unit_illuminance.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitIlluminance` (Foundation). - * @details A unit of measure for illuminance. You typically use instances of ''NSUnitIlluminance'' to represent specific quantities of illuminance using the ''NSMeasurement'' class. \#\#\# Illuminance Illuminance is the luminous flux incident on a surface. The SI unit for illuminance is the lux (lx), which is derived as one lumen per square meter (1lm / 1m2). The ''NSUnitIlluminance'' class defines its ''Dimension/baseUnit()'' as ''lux''. | Name | Method | Symbol | |---|---|---| | Lux | ''lux'' | lx | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,7 +31,7 @@ namespace cocoon explicit UnitIlluminance(Adopt adopt); /** * @brief Returns the `lux` property of `NSUnitIlluminance`. - * @details The lux unit of illuminance. + * @details Base unit - lux * @return The converted Objective-C result. */ static UnitIlluminance lux(); diff --git a/include/generated/unit_information_storage.h b/include/generated/unit_information_storage.h index 8fac272e..d3b0066c 100644 --- a/include/generated/unit_information_storage.h +++ b/include/generated/unit_information_storage.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitInformationStorage` (Foundation). - * @details A unit of measure for quantities of information. Use instances of ''UnitInformationStorage'' to represent quantities of information using the ''NSMeasurement'' class. The base unit of measure for information is the bit, with a nibble representing four bits and a byte representing eight bits. Larger units of information expand on bits and bytes by orders of magnitude in both decimal and binary forms. \#\#\# Information Transfer Units of bits commonly represent the amount of transferred information. | Decimal Bits | Coefficient | Binary Bits | Coefficient | |---|---|---|---| | ''kilobits'' | '1000' | ''kibibits'' | '1024' | | ''megabits'' | '1000e2' | ''mebibits'' | '1024e2' | | ''gigabits'' | '1000e3' | ''gibibits'' | '1024e3' | | ''terabits'' | '1000e4' | ''tebibits'' | '1024e4' | | ''petabits'' | '1000e5' | ''pebibits'' | '1024e5' | | ''exabits'' | '1000e6' | ''exbibits'' | '1024e6' | | ''zettabits'' | '1000e7' | ''zebibits'' | '1024e7' | | ''yottabits'' | '1000e8' | ''yobibits'' | '1024e8' | \#\#\# Information Storage Units of bytes commonly represent the amount of stored information. | Decimal Bytes | Coefficient | Binary Bytes | Coefficient | |---|---|---|---| | ''kilobytes'' | '1000' | ''kibibytes'' | '1024' | | ''megabytes'' | '1000e2' | ''mebibytes'' | '1024e2' | | ''gigabytes'' | '1000e3' | ''gibibytes'' | '1024e3' | | ''terabytes'' | '1000e4' | ''tebibytes'' | '1024e4' | | ''petabytes'' | '1000e5' | ''pebibytes'' | '1024e5' | | ''exabytes'' | '1000e6' | ''exbibytes'' | '1024e6' | | ''zettabytes'' | '1000e7' | ''zebibytes'' | '1024e7' | | ''yottabytes'' | '1000e8' | ''yobibytes'' | '1024e8' | + * @details A dimension for representing amounts of digital information. Base Unit: Byte The values of the below follow IEC 80000-13 definitions and conventions. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -42,199 +42,166 @@ namespace cocoon static UnitInformationStorage bytes(); /** * @brief Returns the `exabits` property of `NSUnitInformationStorage`. - * @details The exabits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage exabits(); /** * @brief Returns the `exabytes` property of `NSUnitInformationStorage`. - * @details The exabytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage exabytes(); /** * @brief Returns the `exbibits` property of `NSUnitInformationStorage`. - * @details The exbibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage exbibits(); /** * @brief Returns the `exbibytes` property of `NSUnitInformationStorage`. - * @details The exbibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage exbibytes(); /** * @brief Returns the `gibibits` property of `NSUnitInformationStorage`. - * @details The gibibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage gibibits(); /** * @brief Returns the `gibibytes` property of `NSUnitInformationStorage`. - * @details The gibibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage gibibytes(); /** * @brief Returns the `gigabits` property of `NSUnitInformationStorage`. - * @details The gigabits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage gigabits(); /** * @brief Returns the `gigabytes` property of `NSUnitInformationStorage`. - * @details The gigabytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage gigabytes(); /** * @brief Returns the `kibibits` property of `NSUnitInformationStorage`. - * @details The kibibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage kibibits(); /** * @brief Returns the `kibibytes` property of `NSUnitInformationStorage`. - * @details The kibibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage kibibytes(); /** * @brief Returns the `kilobits` property of `NSUnitInformationStorage`. - * @details The kilobits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage kilobits(); /** * @brief Returns the `kilobytes` property of `NSUnitInformationStorage`. - * @details The kilobytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage kilobytes(); /** * @brief Returns the `mebibits` property of `NSUnitInformationStorage`. - * @details The mebibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage mebibits(); /** * @brief Returns the `mebibytes` property of `NSUnitInformationStorage`. - * @details The mebibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage mebibytes(); /** * @brief Returns the `megabits` property of `NSUnitInformationStorage`. - * @details The megabits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage megabits(); /** * @brief Returns the `megabytes` property of `NSUnitInformationStorage`. - * @details The megabytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage megabytes(); /** * @brief Returns the `nibbles` property of `NSUnitInformationStorage`. - * @details The nibbles unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage nibbles(); /** * @brief Returns the `pebibits` property of `NSUnitInformationStorage`. - * @details The pebibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage pebibits(); /** * @brief Returns the `pebibytes` property of `NSUnitInformationStorage`. - * @details The pebibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage pebibytes(); /** * @brief Returns the `petabits` property of `NSUnitInformationStorage`. - * @details The petabits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage petabits(); /** * @brief Returns the `petabytes` property of `NSUnitInformationStorage`. - * @details The petabytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage petabytes(); /** * @brief Returns the `tebibits` property of `NSUnitInformationStorage`. - * @details The tebibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage tebibits(); /** * @brief Returns the `tebibytes` property of `NSUnitInformationStorage`. - * @details The tebibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage tebibytes(); /** * @brief Returns the `terabits` property of `NSUnitInformationStorage`. - * @details The terabits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage terabits(); /** * @brief Returns the `terabytes` property of `NSUnitInformationStorage`. - * @details The terabytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage terabytes(); /** * @brief Returns the `yobibits` property of `NSUnitInformationStorage`. - * @details The yobibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage yobibits(); /** * @brief Returns the `yobibytes` property of `NSUnitInformationStorage`. - * @details The yobibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage yobibytes(); /** * @brief Returns the `yottabits` property of `NSUnitInformationStorage`. - * @details The yottabits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage yottabits(); /** * @brief Returns the `yottabytes` property of `NSUnitInformationStorage`. - * @details The yottabytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage yottabytes(); /** * @brief Returns the `zebibits` property of `NSUnitInformationStorage`. - * @details The zebibits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage zebibits(); /** * @brief Returns the `zebibytes` property of `NSUnitInformationStorage`. - * @details The zebibytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage zebibytes(); /** * @brief Returns the `zettabits` property of `NSUnitInformationStorage`. - * @details The zettabits unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage zettabits(); /** * @brief Returns the `zettabytes` property of `NSUnitInformationStorage`. - * @details The zettabytes unit of information storage. * @return The converted Objective-C result. */ static UnitInformationStorage zettabytes(); diff --git a/include/generated/unit_length.h b/include/generated/unit_length.h index e8bb5ca1..162a4db0 100644 --- a/include/generated/unit_length.h +++ b/include/generated/unit_length.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitLength` (Foundation). - * @details A unit of measure for length. You typically use instances of ''UnitLength'' to represent specific quantities of length using the ''NSMeasurement'' class. \#\#\# Length Length is the dimensional extent of matter. The SI unit for length is the meter (m), which is defined in terms of the distance traveled by light in a vacuum. The ''UnitLength'' class defines its ''Dimension/baseUnit()'' as ''meters'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Megameters | ''megameters'' | Mm | '1000000.0' | | Kilometers | ''kilometers'' | kM | '1000.0' | | Hectometers | ''hectometers'' | hm | '100.0' | | Decameters | ''decameters'' | dam | '10.0' | | Meters | ''meters'' | m | '1.0' | | Decimeters | ''decimeters'' | dm | '0.1' | | Centimeters | ''centimeters'' | cm | '0.01' | | Millimeters | ''millimeters'' | mm | '0.001' | | Micrometers | ''micrometers'' | µm | '0.000001' | | Nanometers | ''nanometers'' | nm | '1e-9' | | Picometers | ''picometers'' | pm | '1e-12' | | Inches | ''inches'' | in | '0.0254' | | Feet | ''feet'' | ft | '0.3048' | | Yards | ''yards'' | yd | '0.9144' | | Miles | ''miles'' | mi | '1609.34' | | Scandinavian Miles | ''scandinavianMiles'' | smi | '10000' | | Light Years | ''lightyears'' | ly | '9.461e+15' | | Nautical Miles | ''nauticalMiles'' | NM | '1852' | | Fathoms | ''fathoms'' | ftm | '1.8288' | | Furlongs | ''furlongs'' | fur | '201.168' | | Astronomical Units | ''astronomicalUnits'' | au | '1.496e+11' | | Parsecs | ''parsecs'' | pc | '3.086e+16' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,133 +31,112 @@ namespace cocoon explicit UnitLength(Adopt adopt); /** * @brief Returns the `astronomicalUnits` property of `NSUnitLength`. - * @details The astronomical units unit of length. * @return The converted Objective-C result. */ static UnitLength astronomical_units(); /** * @brief Returns the `centimeters` property of `NSUnitLength`. - * @details The centimeters unit of length. * @return The converted Objective-C result. */ static UnitLength centimeters(); /** * @brief Returns the `decameters` property of `NSUnitLength`. - * @details The decameters unit of length. * @return The converted Objective-C result. */ static UnitLength decameters(); /** * @brief Returns the `decimeters` property of `NSUnitLength`. - * @details The decimeters unit of length. * @return The converted Objective-C result. */ static UnitLength decimeters(); /** * @brief Returns the `fathoms` property of `NSUnitLength`. - * @details The fathoms unit of length. * @return The converted Objective-C result. */ static UnitLength fathoms(); /** * @brief Returns the `feet` property of `NSUnitLength`. - * @details The feet unit of length. * @return The converted Objective-C result. */ static UnitLength feet(); /** * @brief Returns the `furlongs` property of `NSUnitLength`. - * @details The furlongs unit of length. * @return The converted Objective-C result. */ static UnitLength furlongs(); /** * @brief Returns the `hectometers` property of `NSUnitLength`. - * @details The hectometers unit of length. * @return The converted Objective-C result. */ static UnitLength hectometers(); /** * @brief Returns the `inches` property of `NSUnitLength`. - * @details The inches unit of length. * @return The converted Objective-C result. */ static UnitLength inches(); /** * @brief Returns the `kilometers` property of `NSUnitLength`. - * @details The kilometers unit of length. * @return The converted Objective-C result. */ static UnitLength kilometers(); /** * @brief Returns the `lightyears` property of `NSUnitLength`. - * @details The lightyears unit of length. * @return The converted Objective-C result. */ static UnitLength lightyears(); /** * @brief Returns the `megameters` property of `NSUnitLength`. - * @details The megameters unit of length. + * @details Base unit - meters * @return The converted Objective-C result. */ static UnitLength megameters(); /** * @brief Returns the `meters` property of `NSUnitLength`. - * @details The meters unit of length. * @return The converted Objective-C result. */ static UnitLength meters(); /** * @brief Returns the `micrometers` property of `NSUnitLength`. - * @details The micrometers unit of length. * @return The converted Objective-C result. */ static UnitLength micrometers(); /** * @brief Returns the `miles` property of `NSUnitLength`. - * @details The miles unit of length. * @return The converted Objective-C result. */ static UnitLength miles(); /** * @brief Returns the `millimeters` property of `NSUnitLength`. - * @details The millimeters unit of length. * @return The converted Objective-C result. */ static UnitLength millimeters(); /** * @brief Returns the `nanometers` property of `NSUnitLength`. - * @details The nanometers unit of length. * @return The converted Objective-C result. */ static UnitLength nanometers(); /** * @brief Returns the `nauticalMiles` property of `NSUnitLength`. - * @details The nautical miles unit of length. * @return The converted Objective-C result. */ static UnitLength nautical_miles(); /** * @brief Returns the `parsecs` property of `NSUnitLength`. - * @details The parsecs unit of length. * @return The converted Objective-C result. */ static UnitLength parsecs(); /** * @brief Returns the `picometers` property of `NSUnitLength`. - * @details The picometers unit of length. * @return The converted Objective-C result. */ static UnitLength picometers(); /** * @brief Returns the `scandinavianMiles` property of `NSUnitLength`. - * @details The Scandinavian miles unit of length. * @return The converted Objective-C result. */ static UnitLength scandinavian_miles(); /** * @brief Returns the `yards` property of `NSUnitLength`. - * @details The yards unit of length. * @return The converted Objective-C result. */ static UnitLength yards(); diff --git a/include/generated/unit_mass.h b/include/generated/unit_mass.h index aff79677..352972a8 100644 --- a/include/generated/unit_mass.h +++ b/include/generated/unit_mass.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitMass` (Foundation). - * @details A unit of measure for mass. You typically use instances of ''NSUnitMass'' to represent specific quantities of mass using the ''NSMeasurement'' class. \#\#\# Mass Mass is a fundamental property of matter that causes it to resist a force accelerating it. The SI unit for mass is the kilogram (kg), which defined in terms of the mass of the international prototype kilogram. The ''NSUnitMass'' class defines its ''Dimension/baseUnit()'' as ''kilograms'', and provides the following units, which ''UnitConverterLinear'' converters initialize with the given coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Kilograms | ''kilograms'' | kg | '1.0' | | Grams | ''grams'' | g | '0.001' | | Decigrams | ''decigrams'' | dg | '0.0001' | | Centigrams | ''centigrams'' | cg | '0.00001' | | Milligrams | ''milligrams'' | mg | '0.000001' | | Micrograms | ''micrograms'' | µg | '1e-9' | | Nanograms | ''nanograms'' | ng | '1e-12' | | Picograms | ''picograms'' | pg | '1e-15' | | Ounces | ''ounces'' | oz | '0.0283495' | | Pounds | ''pounds'' | lb | '0.453592' | | Stones | ''stones'' | st | '0.157473' | | Metric Tons | ''metricTons'' | t | '1000' | | Short Tons | ''shortTons'' | ton | '907.185' | | Carats | ''carats'' | ct | '0.0002' | | Ounces Troy | ''ouncesTroy'' | oz t | '0.03110348' | | Slugs | ''slugs'' | slug | '14.5939' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,97 +31,82 @@ namespace cocoon explicit UnitMass(Adopt adopt); /** * @brief Returns the `carats` property of `NSUnitMass`. - * @details The carats unit of mass. * @return The converted Objective-C result. */ static UnitMass carats(); /** * @brief Returns the `centigrams` property of `NSUnitMass`. - * @details The centigrams unit of mass. * @return The converted Objective-C result. */ static UnitMass centigrams(); /** * @brief Returns the `decigrams` property of `NSUnitMass`. - * @details The decigrams unit of mass. * @return The converted Objective-C result. */ static UnitMass decigrams(); /** * @brief Returns the `grams` property of `NSUnitMass`. - * @details The grams unit of mass. * @return The converted Objective-C result. */ static UnitMass grams(); /** * @brief Returns the `kilograms` property of `NSUnitMass`. - * @details The kilograms unit of mass. + * @details Base unit - kilograms * @return The converted Objective-C result. */ static UnitMass kilograms(); /** * @brief Returns the `metricTons` property of `NSUnitMass`. - * @details The metric tons unit of mass. * @return The converted Objective-C result. */ static UnitMass metric_tons(); /** * @brief Returns the `micrograms` property of `NSUnitMass`. - * @details The micrograms unit of mass. * @return The converted Objective-C result. */ static UnitMass micrograms(); /** * @brief Returns the `milligrams` property of `NSUnitMass`. - * @details The milligrams unit of mass. * @return The converted Objective-C result. */ static UnitMass milligrams(); /** * @brief Returns the `nanograms` property of `NSUnitMass`. - * @details The nanograms unit of mass. * @return The converted Objective-C result. */ static UnitMass nanograms(); /** * @brief Returns the `ounces` property of `NSUnitMass`. - * @details The ounces unit of mass. * @return The converted Objective-C result. */ static UnitMass ounces(); /** * @brief Returns the `ouncesTroy` property of `NSUnitMass`. - * @details The troy ounces unit of mass. * @return The converted Objective-C result. */ static UnitMass ounces_troy(); /** * @brief Returns the `picograms` property of `NSUnitMass`. - * @details The picograms unit of mass. * @return The converted Objective-C result. */ static UnitMass picograms(); /** * @brief Returns the `poundsMass` property of `NSUnitMass`. - * @details The pounds unit of mass. * @return The converted Objective-C result. */ static UnitMass pounds_mass(); /** * @brief Returns the `shortTons` property of `NSUnitMass`. - * @details The short tons unit of mass. * @return The converted Objective-C result. */ static UnitMass short_tons(); /** * @brief Returns the `slugs` property of `NSUnitMass`. - * @details The slugs unit of mass. * @return The converted Objective-C result. */ static UnitMass slugs(); /** * @brief Returns the `stones` property of `NSUnitMass`. - * @details The stones unit of mass. * @return The converted Objective-C result. */ static UnitMass stones(); diff --git a/include/generated/unit_power.h b/include/generated/unit_power.h index 8365e966..23237f3b 100644 --- a/include/generated/unit_power.h +++ b/include/generated/unit_power.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitPower` (Foundation). - * @details A unit of measure for power. You typically use instances of ''NSUnitPower'' to represent specific quantities of power using the ''NSMeasurement'' class. \#\#\# Power Power is the amount of energy used over time. The SI unit for power is the watt (W), which is derived as one joule per second (1W = 1J / 1s). The ''NSUnitPower'' class defines its ''Dimension/baseUnit()'' as ''watts'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Terawatts | ''terawatts'' | TW | '1e12' | | Gigawatts | ''gigawatts'' | GW | '1e9' | | Megawatts | ''megawatts'' | MW | '1000000.0' | | Kilowatts | ''kilowatts'' | kW | '1000.0' | | Watts | ''watts'' | W | '1' | | Milliwatts | ''milliwatts'' | mW | '0.001' | | Microwatts | ''microwatts'' | µW | '0.000001' | | Nanowatts | ''nanowatts'' | nW | '1e-9' | | Picowatts | ''picowatts'' | pW | '1e-12' | | Femtowatts | ''femtowatts'' | fW | '1e-15' | | Horsepower | ''horsepower'' | hp | '745.7' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,67 +31,57 @@ namespace cocoon explicit UnitPower(Adopt adopt); /** * @brief Returns the `femtowatts` property of `NSUnitPower`. - * @details The femtowatts unit of power. * @return The converted Objective-C result. */ static UnitPower femtowatts(); /** * @brief Returns the `gigawatts` property of `NSUnitPower`. - * @details The gigawatts unit of power. * @return The converted Objective-C result. */ static UnitPower gigawatts(); /** * @brief Returns the `horsepower` property of `NSUnitPower`. - * @details The horsepower unit of power. * @return The converted Objective-C result. */ static UnitPower horsepower(); /** * @brief Returns the `kilowatts` property of `NSUnitPower`. - * @details The kilowatts unit of power. * @return The converted Objective-C result. */ static UnitPower kilowatts(); /** * @brief Returns the `megawatts` property of `NSUnitPower`. - * @details The megawatts unit of power. * @return The converted Objective-C result. */ static UnitPower megawatts(); /** * @brief Returns the `microwatts` property of `NSUnitPower`. - * @details The microwatts unit of power. * @return The converted Objective-C result. */ static UnitPower microwatts(); /** * @brief Returns the `milliwatts` property of `NSUnitPower`. - * @details The milliwatts unit of power. * @return The converted Objective-C result. */ static UnitPower milliwatts(); /** * @brief Returns the `nanowatts` property of `NSUnitPower`. - * @details The nanowatts unit of power. * @return The converted Objective-C result. */ static UnitPower nanowatts(); /** * @brief Returns the `picowatts` property of `NSUnitPower`. - * @details The picowatts unit of power. * @return The converted Objective-C result. */ static UnitPower picowatts(); /** * @brief Returns the `terawatts` property of `NSUnitPower`. - * @details The terawatts unit of power. + * @details Base unit - watts * @return The converted Objective-C result. */ static UnitPower terawatts(); /** * @brief Returns the `watts` property of `NSUnitPower`. - * @details The watts unit of power. * @return The converted Objective-C result. */ static UnitPower watts(); diff --git a/include/generated/unit_pressure.h b/include/generated/unit_pressure.h index 57306d6a..d2b2e670 100644 --- a/include/generated/unit_pressure.h +++ b/include/generated/unit_pressure.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitPressure` (Foundation). - * @details A unit of measure for pressure. You typically use instances of ''NSUnitPressure'' to represent specific quantities of pressure using the ''NSMeasurement'' class. \#\#\# Pressure Pressure is the normal force over a surface. The SI unit for pressure is the pascal (Pa), which is derived as one newton of force over one square meter ('1 Pa = 1 N / 1 m'2). The ''UnitPressure'' class defines its ''Dimension/baseUnit()'' as ''newtonsPerMetersSquared'' and provides the following units, which ''UnitConverterLinear'' converters initialize with the given coefficients: | Name | Method | Symbol | Definition | |---|---|---|---| | Newtons Per Meter Squared (Equivalent to Pascals) | ''newtonsPerMetersSquared'' | N/m² | '1.0' | | Gigapascals | ''gigapascals'' | GPa | '1e9' | | Megapascals | ''megapascals'' | MPa | '1000000.0' | | Kilopascals | ''kilopascals'' | kPa | '1000.0' | | Hectopascals | ''hectopascals'' | hPa | '100.0' | | Inches of Mercury | ''inchesOfMercury'' | inHg | '3386.39' | | Bars | ''bars'' | bar | '100000' | | Millibars | ''millibars'' | mbar | '100' | | Millimeters of Mercury | ''millimetersOfMercury'' | mmHg | '133.322' | | Pounds Per Square Inch | ''poundsForcePerSquareInch'' | psi | '6894.76' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,61 +31,52 @@ namespace cocoon explicit UnitPressure(Adopt adopt); /** * @brief Returns the `bars` property of `NSUnitPressure`. - * @details The bars unit of pressure. * @return The converted Objective-C result. */ static UnitPressure bars(); /** * @brief Returns the `gigapascals` property of `NSUnitPressure`. - * @details The gigapascals unit of pressure. * @return The converted Objective-C result. */ static UnitPressure gigapascals(); /** * @brief Returns the `hectopascals` property of `NSUnitPressure`. - * @details The hectopascals unit of pressure. * @return The converted Objective-C result. */ static UnitPressure hectopascals(); /** * @brief Returns the `inchesOfMercury` property of `NSUnitPressure`. - * @details The inches of mercury unit of pressure. * @return The converted Objective-C result. */ static UnitPressure inches_of_mercury(); /** * @brief Returns the `kilopascals` property of `NSUnitPressure`. - * @details The kilopascals unit of pressure. * @return The converted Objective-C result. */ static UnitPressure kilopascals(); /** * @brief Returns the `megapascals` property of `NSUnitPressure`. - * @details The megapascals unit of pressure. * @return The converted Objective-C result. */ static UnitPressure megapascals(); /** * @brief Returns the `millibars` property of `NSUnitPressure`. - * @details The millibars unit of pressure. * @return The converted Objective-C result. */ static UnitPressure millibars(); /** * @brief Returns the `millimetersOfMercury` property of `NSUnitPressure`. - * @details The millimeters of mercury unit of pressure. * @return The converted Objective-C result. */ static UnitPressure millimeters_of_mercury(); /** * @brief Returns the `newtonsPerMetersSquared` property of `NSUnitPressure`. - * @details The newtons per meters squared unit of pressure. + * @details Base unit - newtonsPerMetersSquared (equivalent to 1 pascal) * @return The converted Objective-C result. */ static UnitPressure newtons_per_meters_squared(); /** * @brief Returns the `poundsForcePerSquareInch` property of `NSUnitPressure`. - * @details The pounds per square inch unit of pressure. * @return The converted Objective-C result. */ static UnitPressure pounds_force_per_square_inch(); diff --git a/include/generated/unit_speed.h b/include/generated/unit_speed.h index 773dff78..ca04d7dd 100644 --- a/include/generated/unit_speed.h +++ b/include/generated/unit_speed.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitSpeed` (Foundation). - * @details A unit of measure for speed. You typically use instances of ''NSUnitSpeed'' to represent specific quantities of speed using the ''NSMeasurement'' class. \#\#\# Speed Speed is the magnitude of velocity, or the rate of change of position. Speed can be expressed by SI derived units in terms of meters per second (m/s), and is also commonly expressed in terms of kilometers per hour (km/h) and miles per hour (mph). The ''NSUnitSpeed'' class defines its ''Dimension/baseUnit()'' as ''metersPerSecond'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Meters Per Second | ''metersPerSecond'' | m/s | '1.0' | | Kilometers Per Hour | ''kilometersPerHour'' | km/h | '0.277778' | | Miles Per Hour | ''milesPerHour'' | mph | '0.44704' | | Knots | ''knots'' | kn | '0.514444' | The base unit is ''metersPerSecond'' and is accessed via ''NSDimension/baseUnit'' on the ''NSDimension'' protocol. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,25 +31,22 @@ namespace cocoon explicit UnitSpeed(Adopt adopt); /** * @brief Returns the `kilometersPerHour` property of `NSUnitSpeed`. - * @details The kilometers per hour unit of speed. * @return The converted Objective-C result. */ static UnitSpeed kilometers_per_hour(); /** * @brief Returns the `knots` property of `NSUnitSpeed`. - * @details The knots unit of speed. * @return The converted Objective-C result. */ static UnitSpeed knots(); /** * @brief Returns the `metersPerSecond` property of `NSUnitSpeed`. - * @details The meters per second unit of speed. + * @details Base unit - metersPerSecond * @return The converted Objective-C result. */ static UnitSpeed meters_per_second(); /** * @brief Returns the `milesPerHour` property of `NSUnitSpeed`. - * @details The miles per hour unit of speed. * @return The converted Objective-C result. */ static UnitSpeed miles_per_hour(); diff --git a/include/generated/unit_temperature.h b/include/generated/unit_temperature.h index e428e5fd..85e22dc3 100644 --- a/include/generated/unit_temperature.h +++ b/include/generated/unit_temperature.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitTemperature` (Foundation). - * @details A unit of measure for temperature. You typically use instances of ''NSUnitTemperature'' to represent specific quantities of temperature using the ''NSMeasurement'' class. \#\#\# Temperature Temperature is a comparative measure of thermal energy. The SI unit for temperature is the kelvin (K), which is defined in terms of the triple point of water. Temperature is also commonly measured by degrees of various scales, including Celsius (°C) and Fahrenheit (°F). The ''NSUnitTemperature'' class defines its ''Dimension/baseUnit()'' to be ''kelvin'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients and constants: | Name | Method | Symbol | Coefficient | Constant | |---|---|---|---|---| | Kelvin | ''kelvin'' | K | '1' | '0' | | Degree Celsius | ''celsius'' | °C | '1.0' | '273.15' | | Degree Fahrenheit | ''fahrenheit'' | °F | '0.55555555555556' | '255.37222222222427' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,19 +31,17 @@ namespace cocoon explicit UnitTemperature(Adopt adopt); /** * @brief Returns the `celsius` property of `NSUnitTemperature`. - * @details The degrees Celsius unit of temperature. * @return The converted Objective-C result. */ static UnitTemperature celsius(); /** * @brief Returns the `fahrenheit` property of `NSUnitTemperature`. - * @details The degrees Fahrenheit unit of temperature. * @return The converted Objective-C result. */ static UnitTemperature fahrenheit(); /** * @brief Returns the `kelvin` property of `NSUnitTemperature`. - * @details The kelvin unit of temperature. + * @details Base unit - kelvin * @return The converted Objective-C result. */ static UnitTemperature kelvin(); diff --git a/include/generated/unit_volume.h b/include/generated/unit_volume.h index c731314b..5e4bca37 100644 --- a/include/generated/unit_volume.h +++ b/include/generated/unit_volume.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUnitVolume` (Foundation). - * @details A unit of measure for volume. You typically use instances of ''NSUnitVolume'' to represent specific quantities of volume using the ''NSMeasurement'' class. \#\#\# Volume Volume is a quantity of the extend of matter in three dimensions. The SI accepted unit of volume is the liter (L), which is derived as one cubic decimeter (1 dm3). Volume is also commonly expressed in terms of cubic meters (m3), gallons (gal), and cups (cup). The ''NSUnitVolume'' class defines its ''Dimension/baseUnit()'' as ''liters'', and provides the following units, which are initialized using ''UnitConverterLinear'' converters with the specified coefficients: | Name | Method | Symbol | Coefficient | |---|---|---|---| | Megaliters | ''megaliters'' | ML | '1000000.0' | | Kiloliters | ''kiloliters'' | kL | '1000.0' | | Liters | ''liters'' | L | '1.0' | | Deciliters | ''deciliters'' | dL | '0.1' | | Centiliters | ''centiliters'' | cL | '0.01' | | Milliliters | ''milliliters'' | mL | '0.001' | | Cubic Kilometers | ''cubicKilometers'' | km³ | '1e12' | | Cubic Meters | ''cubicMeters'' | m³ | '1000.0' | | Cubic Decimeters | ''cubicDecimeters'' | dm³ | '1.0' | | Cubic Centimeters | ''cubicCentimeters'' | cm³ | '0.001' | | Cubic Millimeters | ''cubicMillimeters'' | mm³ | '0.000001' | | Cubic Inches | ''cubicInches'' | in³ | '0.0163871' | | Cubic Feet | ''cubicFeet'' | ft³ | '28.3168' | | Cubic Yards | ''cubicYards'' | yd³ | '764.555' | | Cubic Miles | ''cubicMiles'' | mi³ | '4.168e+12' | | Acre Feet | ''acreFeet'' | af | '1.233e+6' | | Bushels | ''bushels'' | bsh | '35.2391' | | Teaspoons | ''teaspoons'' | tsp | '0.00492892' | | Tablespoons | ''tablespoons'' | tbsp | '0.0147868' | | Fluid Ounces | ''fluidOunces'' | fl oz | '0.0295735' | | Cups | ''cups'' | cup | '0.24' | | Pints | ''pints'' | pt | '0.473176' | | Quarts | ''quarts'' | qt | '0.946353' | | Gallons | ''gallons'' | gal | '3.78541' | | Imperial Teaspoons | ''imperialTeaspoons'' | tsp | '0.00591939' | | Imperial Tablespoons | ''imperialTablespoons'' | tbsp | '0.0177582' | | Imperial Fluid Ounces | ''imperialFluidOunces'' | fl oz | '0.0284131' | | Imperial Pints | ''imperialPints'' | pt | '0.568261' | | Imperial Quarts | ''imperialQuarts'' | qt | '1.13652' | | Imperial Gallons | ''imperialGallons'' | gal | '4.54609' | | Metric Cups | ''metricCups'' | metric cup | '0.25' | * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Dimension. * @@ -32,187 +31,157 @@ namespace cocoon explicit UnitVolume(Adopt adopt); /** * @brief Returns the `acreFeet` property of `NSUnitVolume`. - * @details The acre-feet unit of volume. * @return The converted Objective-C result. */ static UnitVolume acre_feet(); /** * @brief Returns the `bushels` property of `NSUnitVolume`. - * @details The bushels unit of volume. * @return The converted Objective-C result. */ static UnitVolume bushels(); /** * @brief Returns the `centiliters` property of `NSUnitVolume`. - * @details The centiliters unit of volume. * @return The converted Objective-C result. */ static UnitVolume centiliters(); /** * @brief Returns the `cubicCentimeters` property of `NSUnitVolume`. - * @details The cubic centimeters unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_centimeters(); /** * @brief Returns the `cubicDecimeters` property of `NSUnitVolume`. - * @details The cubic decimeters unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_decimeters(); /** * @brief Returns the `cubicFeet` property of `NSUnitVolume`. - * @details The cubic feet unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_feet(); /** * @brief Returns the `cubicInches` property of `NSUnitVolume`. - * @details The cubic inches unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_inches(); /** * @brief Returns the `cubicKilometers` property of `NSUnitVolume`. - * @details The cubic kilometers unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_kilometers(); /** * @brief Returns the `cubicMeters` property of `NSUnitVolume`. - * @details The cubic meters unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_meters(); /** * @brief Returns the `cubicMiles` property of `NSUnitVolume`. - * @details The cubic miles unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_miles(); /** * @brief Returns the `cubicMillimeters` property of `NSUnitVolume`. - * @details The cubic millimeters unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_millimeters(); /** * @brief Returns the `cubicYards` property of `NSUnitVolume`. - * @details The cubic yards unit of volume. * @return The converted Objective-C result. */ static UnitVolume cubic_yards(); /** * @brief Returns the `cups` property of `NSUnitVolume`. - * @details The cups unit of volume. * @return The converted Objective-C result. */ static UnitVolume cups(); /** * @brief Returns the `deciliters` property of `NSUnitVolume`. - * @details The deciliters unit of volume. * @return The converted Objective-C result. */ static UnitVolume deciliters(); /** * @brief Returns the `fluidOunces` property of `NSUnitVolume`. - * @details The fluid ounces unit of volume. * @return The converted Objective-C result. */ static UnitVolume fluid_ounces(); /** * @brief Returns the `gallons` property of `NSUnitVolume`. - * @details The gallons unit of volume. * @return The converted Objective-C result. */ static UnitVolume gallons(); /** * @brief Returns the `imperialFluidOunces` property of `NSUnitVolume`. - * @details The imperial fluid ounces unit of volume. * @return The converted Objective-C result. */ static UnitVolume imperial_fluid_ounces(); /** * @brief Returns the `imperialGallons` property of `NSUnitVolume`. - * @details The imperial gallons unit of volume. * @return The converted Objective-C result. */ static UnitVolume imperial_gallons(); /** * @brief Returns the `imperialPints` property of `NSUnitVolume`. - * @details The imperial pints unit of volume. * @return The converted Objective-C result. */ static UnitVolume imperial_pints(); /** * @brief Returns the `imperialQuarts` property of `NSUnitVolume`. - * @details The imperial quarts unit of volume. * @return The converted Objective-C result. */ static UnitVolume imperial_quarts(); /** * @brief Returns the `imperialTablespoons` property of `NSUnitVolume`. - * @details The imperial tablespoons unit of volume. * @return The converted Objective-C result. */ static UnitVolume imperial_tablespoons(); /** * @brief Returns the `imperialTeaspoons` property of `NSUnitVolume`. - * @details The imperial teaspoons unit of volume. * @return The converted Objective-C result. */ static UnitVolume imperial_teaspoons(); /** * @brief Returns the `kiloliters` property of `NSUnitVolume`. - * @details The kiloliters unit of volume. * @return The converted Objective-C result. */ static UnitVolume kiloliters(); /** * @brief Returns the `liters` property of `NSUnitVolume`. - * @details The liters unit of volume. * @return The converted Objective-C result. */ static UnitVolume liters(); /** * @brief Returns the `megaliters` property of `NSUnitVolume`. - * @details The megaliters unit of volume. + * @details Base unit - liters * @return The converted Objective-C result. */ static UnitVolume megaliters(); /** * @brief Returns the `metricCups` property of `NSUnitVolume`. - * @details The metric cups unit of volume. * @return The converted Objective-C result. */ static UnitVolume metric_cups(); /** * @brief Returns the `milliliters` property of `NSUnitVolume`. - * @details The milliliters unit of volume. * @return The converted Objective-C result. */ static UnitVolume milliliters(); /** * @brief Returns the `pints` property of `NSUnitVolume`. - * @details The pints unit of volume. * @return The converted Objective-C result. */ static UnitVolume pints(); /** * @brief Returns the `quarts` property of `NSUnitVolume`. - * @details The quarts unit of volume. * @return The converted Objective-C result. */ static UnitVolume quarts(); /** * @brief Returns the `tablespoons` property of `NSUnitVolume`. - * @details The tablespoons unit of volume. * @return The converted Objective-C result. */ static UnitVolume tablespoons(); /** * @brief Returns the `teaspoons` property of `NSUnitVolume`. - * @details The teaspoons unit of volume. * @return The converted Objective-C result. */ static UnitVolume teaspoons(); diff --git a/include/generated/url.h b/include/generated/url.h index 91f9d2ed..faf07115 100644 --- a/include/generated/url.h +++ b/include/generated/url.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURL` (Foundation). - * @details An object that represents the location of a resource, such as an item on a remote server or the path to a local file. In Swift, this object bridges to ''URL''; use ''NSURL'' when you need reference semantics or other Foundation-specific behavior. You can use URL objects to construct URLs and access their parts. For URLs that represent local files, you can also manipulate properties of those files directly, such as changing the file's last modification date. Finally, you can pass URL objects to other APIs to retrieve the contents of those URLs. For example, you can use the ''URLSession'', ''NSURLConnection'', and ''NSURLDownload'' classes to access the contents of remote resources, as described in \. URL objects are the preferred way to refer to local files. Most objects that read data from or write data to a file have methods that accept an ''NSURL'' object instead of a pathname as the file reference. For example, you can get the contents of a local file URL as an 'NSString' object using the ''NSString/init(contentsOfURL:encoding:)-715fw'' initializer, or as an 'NSData' object using the ''NSData/init(contentsOfURL:options:)-5abi3'' initializer. You can also use URLs for interapplication communication. In macOS, the \ class provides the \ method to open a location specified by a URL. Similarly, in iOS, the \ class provides the \ method. The ''NSURL'' class is "toll-free bridged" with its Core Foundation counterpart, \. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html\#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. > Important: > The Swift overlay to the Foundation framework provides the ''URL'' structure, which bridges to the ''NSURL'' class. For more information about value types, see [Classes and Structures](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/Swift_Programming_Language/ClassesAndStructures.html\#//apple_ref/doc/uid/TP40014097-CH13) in [The Swift Programming Language (Swift 4.1)](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/Swift_Programming_Language/index.html\#//apple_ref/doc/uid/TP40014097) and [Working with Cocoa Frameworks](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/BuildingCocoaApps/WorkingWithCocoaDataTypes.html\#//apple_ref/doc/uid/TP40014216-CH6) in [Using Swift with Cocoa and Objective-C (Swift 4.1)](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/BuildingCocoaApps/index.html\#//apple_ref/doc/uid/TP40014216). \#\#\# Structure of a URL An ''NSURL'' object is composed of two parts—a potentially 'nil' base URL and a string that is resolved relative to the base URL. An ''NSURL'' object is considered absolute if its string part is fully resolved without a base; all other URLs are considered relative. For example, when constructing an 'NSURL' object, you might specify 'file:///path/to/user/' as the base URL and 'folder/file.html' as the string part, as follows: '''objc NSURL baseURL = [NSURL fileURLWithPath:\@"file:///path/to/user/"]; NSURL URL = [NSURL URLWithString:\@"folder/file.html" relativeToURL:baseURL]; NSLog(\@"absoluteURL = \%\@", [URL absoluteURL]); ''' When fully resolved, the absolute URL is 'file:///path/to/user/folder/file.html'. A URL can be also be divided into pieces based on its structure. For example, the URL 'https://johnny:p4ssw0rd\@www.example.com:443/script.ext;param=value?query=value\#ref' contains the following URL components: | Component | Value | |---|---| | ''scheme'' | 'https' | | ''user'' | 'johnny' | | ''password'' | 'p4ssw0rd' | | ''host'' | 'www.example.com' | | ''port'' | '443' | | ''path'' | '/script.ext' | | ''pathExtension'' | 'ext' | | ''pathComponents'' | '["/", "script.ext"]' | | ''parameterString'' | 'param=value' | | ''query'' | 'query=value' | | ''fragment'' | 'ref' | The ''NSURL'' class provides properties that let you examine each of these components. > Important: > For apps linked on or after iOS 17 and aligned OS versions, ''NSURL'' parsing has updated from the obsolete RFC 1738/1808 parsing to the same [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt) parsing as ''NSURLComponents''. This unifies the parsing behaviors of the 'NSURL' and 'NSURLComponents' APIs. Now, 'NSURL' automatically percent- and IDNA-encodes invalid characters to help create a valid URL. > > To check if a 'URLString' is strictly valid according to the RFC, use the new '[NSURL URLWithString:URLString encodingInvalidCharacters:NO]' method. This method leaves all characters as they are and returns 'nil' if 'URLString' is explicitly invalid. For apps linked before iOS 17, the ''NSURL'' class parses URLs according to [RFC 1808](https://tools.ietf.org/html/rfc1808), [RFC 1738](https://tools.ietf.org/html/rfc1738), and [RFC 2732](https://tools.ietf.org/html/rfc2732). \#\#\# Bookmarks and Security Scope Starting with OS X v10.6 and iOS 4.0, the ''NSURL'' class provides a facility for creating and using bookmark objects. A bookmark provides a persistent reference to a file-system resource. When you resolve a bookmark, you obtain a URL to the resource's current location. A bookmark's association with a file-system resource (typically a file or folder) usually continues to work if the user moves or renames the resource, or if the user relaunches your app or restarts the system. For a general introduction to using bookmarks, read [Locating Files Using Bookmarks](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/AccessingFilesandDirectories/AccessingFilesandDirectories.html\#//apple_ref/doc/uid/TP40010672-CH3-SW10) in [File System Programming Guide](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/Introduction/Introduction.html\#//apple_ref/doc/uid/TP40010672). In a macOS app that adopts App Sandbox, you can use security-scoped bookmarks to gain access to file-system resources outside your app's sandbox. These bookmarks preserve the user's intent to give your app access to a resource across app launches. For details on how this works, including information on the entitlements you need in your Xcode project, read [Security-Scoped Bookmarks and Persistent Resource Access](https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html\#//apple_ref/doc/uid/TP40011183-CH3-SW16) in [App Sandbox Design Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AboutAppSandbox/AboutAppSandbox.html\#//apple_ref/doc/uid/TP40011183). The methods for using security-scoped bookmarks are described in this document in Working with Bookmark Data. When you resolve a security-scoped bookmark, you get a security-scoped URL. \#\#\# Security-Scoped URLs Security-scoped URLs provide access to resources outside an app's sandbox. In macOS, you get access to security-scoped URLs when you resolve a security-scoped bookmark. In iOS, apps that open or move documents using a \ also receive security-scoped URLs. To gain access to a security-scoped URL, you must call the ''startAccessingSecurityScopedResource()'' method (or its Core Foundation equivalent, the \ function). For iOS apps, if you use a \ to access the URL, it automatically manages the security-scoped URL for you. If 'startAccessingSecurityScopedResource' (or 'CFUrLStartAccessingSecurityScopedResource') returns \, you must relinquish your access by calling the ''stopAccessingSecurityScopedResource()'' method (or its Core Foundation equivalent, the \ function). You should relinquish your access as soon as you have finished using the file. After you call these methods, you immediately lose access to the resource in question. > Warning: > If you fail to relinquish your access when you no longer need a file-system resource, your app leaks kernel resources. If sufficient kernel resources are leaked, your app loses its ability to add file-system locations to its sandbox, using Powerbox, security-scoped bookmarks, or similar APIs, until relaunched. \#\#\#\# Security-Scoped URLs and String Paths In a macOS app, when you copy a security-scoped URL, the copy has the security scope of the original. You gain access to the file-system resource (that the URL points to) just as you would with the original URL: by calling the ''startAccessingSecurityScopedResource()'' method (or its Core Foundation equivalent). If you need a security-scoped URL's path as a string value (as provided by the ''path'' method), such as to provide to an API that requires a string value, obtain the path from the URL as needed. Note, however, that a string-based path obtained from a security-scoped URL does not have security scope and you cannot use that string to obtain access to a security-scoped resource. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -58,14 +57,12 @@ namespace cocoon explicit URL(Adopt adopt); /** * @brief Calls `-[NSURL URLByAppendingPathComponent:]`. - * @details Returns a new URL by appending a path component to the original URL. If the original URL does not end with a forward slash and 'pathComponent' does not begin with a forward slash, a forward slash is inserted between the two parts of the returned URL, unless the original URL is the empty string. If the receiver is a file URL and 'pathComponent' does not end with a trailing slash, this method may read file metadata to determine whether the resulting path is a directory. This is done synchronously, and may have significant performance costs if the receiver is a location on a network mounted filesystem. You can instead use ''URLByAppendingPathComponent:isDirectory:'' if you know whether the resulting path is a directory to avoid this file metadata operation. - Parameter pathComponent: The path component to add to the URL, in its original form (not URL encoded). - Returns: A new URL with 'pathComponent' appended. * @param path_component Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URL url_by_appending_path_component(const std::string& path_component) const; /** * @brief Calls `-[NSURL URLByAppendingPathComponent:isDirectory:]`. - * @details Returns a new URL by appending a path component to the original URL, along with a trailing slash if the component is a directory. If the original URL does not end with a forward slash and 'pathComponent' does not begin with a forward slash, a forward slash is inserted between the two parts of the returned URL, unless the original URL is the empty string. - Parameters: - pathComponent: The path component to add to the URL. - isDirectory: If 'YES', a trailing slash is appended after 'pathComponent'. - Returns: A new URL with 'pathComponent' appended. * @param path_component Argument converted to the Objective-C parameter of the same role. * @param is_directory Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -73,14 +70,13 @@ namespace cocoon URL url_by_appending_path_component(const std::string& path_component, bool is_directory) const; /** * @brief Calls `-[NSURL URLByAppendingPathExtension:]`. - * @details Returns a new URL by appending a path extension to the original URL. If the original URL ends with one or more forward slashes, these are removed from the returned URL. A period is inserted between the two parts of the new URL. - Parameter pathExtension: The path extension to add to the URL. - Returns: A new URL with 'pathExtension' appended. * @param path_extension Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URL url_by_appending_path_extension(const std::string& path_extension) const; /** * @brief Calls `+[NSURL URLByResolvingAliasFileAtURL:options:error:]`. - * @details Returns a new URL made by resolving the alias file at the given URL. Creates and initializes a new URL based on the alias file at 'url'. Use this method to resolve bookmark data that was saved using ''NSURL/writeBookmarkData(:to:options:)'' and resolve that data in one step. If the 'url' argument does not refer to an alias file as defined by the 'NSURLIsAliasFileKey' property, this method returns the 'url' argument. If the 'url' argument is unreachable, this method returns 'nil' and the optional error argument is populated. > Note: The ''NSURL/BookmarkResolutionOptions/withSecurityScope'' option is not supported by this method. - Parameters: - url: The URL pointing to the alias file. - options: Options taken into account when resolving the bookmark data. - error: The error that occurred while trying to resolve the provided URL. - Returns: A new URL created by resolving the bookmark data derived from the provided alias file. If an error occurs, this method returns 'nil'. + * @details Creates and initializes a NSURL that refers to the location specified by resolving the alias file at url. If the url argument does not refer to an alias file as defined by the NSURLIsAliasFileKey property, the NSURL returned is the same as url argument. This method fails and returns nil if the url argument is unreachable, or if the original file or directory could not be located or is not reachable, or if the original file or directory is on a volume that could not be located or mounted. If this method fails, the optional error is populated. The NSURLBookmarkResolutionWithSecurityScope option is not supported by this method. * @param url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -88,7 +84,7 @@ namespace cocoon static URL url_by_resolving_alias_file_at_url(const URL& url, URLBookmarkResolutionOptions options); /** * @brief Calls `+[NSURL URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:]`. - * @details Returns a new URL made by resolving bookmark data. This method fails if the original file or directory could not be located or is on a volume that could not be mounted. If this method fails, you can use the ''NSURL/resourceValuesForKeys:fromBookmarkData:'' method to obtain information about the bookmark, such as the last known path (''NSURLPathKey'') to help the user decide how to proceed. To obtain a security-scoped URL from a security-scoped bookmark, call this method using the ''NSURLBookmarkResolutionWithSecurityScope'' option. In addition, to use security scope, you must first have enabled the appropriate entitlements for your app, as described in [Enabling Security-Scoped Bookmark and URL Access](https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html\#//apple_ref/doc/uid/TP40011195-CH4-SW18). To then obtain access to the file-system resource pointed to by a security-scoped URL (in other words, to bring the resource into your app's sandbox), call the ''NSURL/startAccessingSecurityScopedResource'' method on the URL. For an app-scoped bookmark, no sandboxed app other than the one that created the bookmark can obtain access to the file-system resource that the URL (obtained from the bookmark) points to. For a document-scoped bookmark, any sandboxed app that has access to the bookmark data itself, and has access to the document that owns the bookmark, can obtain access to the resource. > Note: Security-scoped bookmarks are not available in versions of macOS prior to OS X v10.7.3. - Parameters: - bookmarkData: The bookmark data the URL is derived from. - options: Options taken into account when resolving the bookmark data. To resolve a security-scoped bookmark to support App Sandbox, you must include the ''NSURLBookmarkResolutionWithSecurityScope'' option. - relativeURL: The base URL that the bookmark data is relative to. To resolve an app-scoped bookmark, use a value of 'nil'. To resolve a document-scoped bookmark, use the absolute path to the document from which you retrieved the bookmark. - isStale: On return, if 'YES', the bookmark data is stale. Your app should create a new bookmark using the returned URL and use it in place of any stored copies of the existing bookmark. - error: The error that occurred in the case that the URL cannot be created. - Returns: A new URL made by resolving 'bookmarkData'. + * @details Creates and Initializes an NSURL that refers to a location specified by resolving bookmark data. If this method returns nil, the optional error is populated. * @param bookmark_data Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. * @param relative_url Argument converted to the Objective-C parameter of the same role. @@ -112,7 +108,6 @@ namespace cocoon static URL url_with_data_representation(const std::vector& data, const URL& base_url); /** * @brief Calls `+[NSURL URLWithString:]`. - * @details Returns a newly created NSURL initialized with the given URL string. * @param url_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -127,7 +122,6 @@ namespace cocoon static URL url_with_string(const std::string& url_string, bool encoding_invalid_characters); /** * @brief Calls `+[NSURL URLWithString:relativeToURL:]`. - * @details Returns a newly created NSURL initialized with the given URL string, relative to a base URL. * @param url_string Argument converted to the Objective-C parameter of the same role. * @param base_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -143,14 +137,14 @@ namespace cocoon static URL absolute_url_with_data_representation(const std::vector& data, const URL& base_url); /** * @brief Calls `+[NSURL bookmarkDataWithContentsOfURL:error:]`. - * @details Initializes and returns bookmark data derived from an alias file pointed to by a specified URL. This method doesn't check to see if 'bookmarkFileURL' points to an alias file. This allows this method to work with any file containing bookmark data. If 'bookmarkFileURL' refers to a file which does not contain bookmark data or to a non-file object, such as a directory or symbolic link, this method returns 'nil' and produces an error. If 'bookmarkFileURL' refers to an alias file created prior to OS X v10.6 that contains Alias Manager information but no bookmark data, this method synthesizes bookmark data for the file. This method returns 'nil' if bookmark data cannot be created. - Parameters: - bookmarkFileURL: The URL that points to a file containing bookmark data. - error: The error that occurred in the case that the bookmark data cannot be derived. - Returns: The bookmark data for the alias file. + * @details Initializes and returns bookmark data derived from an alias file pointed to by a specified URL. If bookmarkFileURL refers to an alias file created prior to OS X v10.6 that contains Alias Manager information but no bookmark data, this method synthesizes bookmark data for the file. If this method returns nil, the optional error is populated. * @param bookmark_file_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::vector bookmark_data_with_contents_of_url(const URL& bookmark_file_url); /** * @brief Calls `-[NSURL bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:]`. - * @details Returns bookmark data for the URL, created with specified options and resource values. This method returns bookmark data that can later be resolved into a URL object for a file even if the user moves or renames it (if the volume format on which the file resides supports doing so). If the specified URL is not a file URL, this method returns a bookmark containing only the URL, and the 'options' and 'keys' parameters are ignored. You can also use this method to create a security-scoped bookmark to support App Sandbox. Before you do so, you must first enable the appropriate entitlements for your app. In addition, be sure to understand the behavior of the 'options' and 'relativeURL' parameters. For an app-scoped bookmark, no sandboxed app other than the one that created the bookmark can obtain access to the file-system resource that the URL (obtained from the bookmark) points to. For a document-scoped bookmark, any sandboxed app that has access to the bookmark data itself, and has access to the document that owns the bookmark, can obtain access to the resource. - Parameters: - options: Options taken into account when creating the bookmark for the URL. - keys: An array of names of URL resource properties to store as part of the bookmark. - relativeURL: The URL that the bookmark data will be relative to. For an app-scoped bookmark, use 'nil'. For a document-scoped bookmark, use the absolute path to the document file that is to own the bookmark. - error: The error that occurred in the case that the bookmark data cannot be created. - Returns: Bookmark data for the URL, or 'nil' if an error occurred. + * @details Returns bookmark data for the URL, created with specified options and resource values. If this method returns nil, the optional error is populated. * @param options Argument converted to the Objective-C parameter of the same role. * @param keys Argument converted to the Objective-C parameter of the same role. * @param relative_url Argument converted to the Objective-C parameter of the same role. @@ -159,19 +153,18 @@ namespace cocoon std::vector bookmark_data_with_options(URLBookmarkCreationOptions options, const std::vector& keys, const URL& relative_url) const; /** * @brief Calls `-[NSURL checkPromisedItemIsReachableAndReturnError:]`. - * @details Returns whether the promised item can be reached. This method behaves identically to 'checkResourceIsReachableAndReturnError:', but works on promised items. A promised item is not guaranteed to have its contents in the file system until you use a file coordinator to perform a coordinated read on its URL, which causes the contents to be downloaded or otherwise generated. - Parameter error: The error that occurred when the promised item could not be reached. - Returns: 'YES' if the promised item is reachable; otherwise, 'NO'. * @return The converted Objective-C result. */ bool check_promised_item_is_reachable_and_return_error() const; /** * @brief Calls `-[NSURL checkResourceIsReachableAndReturnError:]`. - * @details Returns whether the resource pointed to by a file URL can be reached. This method synchronously checks if the file at the provided URL is reachable. Checking reachability is appropriate when making decisions that do not require other immediate operations on the resource, such as periodic maintenance of user interface state that depends on the existence of a specific document. If your app must perform operations on the file, such as opening it or copying resource properties, it is more efficient to attempt the operation and handle any failure that may occur. This method is currently applicable only to URLs for file system resources. For other URL types, 'NO' is returned. - Parameter error: The error that occurred when the resource could not be reached. - Returns: 'YES' if the resource is reachable; otherwise, 'NO'. + * @details Returns whether the URL's resource exists and is reachable. This method synchronously checks if the resource's backing store is reachable. Checking reachability is appropriate when making decisions that do not require other immediate operations on the resource, e.g. periodic maintenance of UI state that depends on the existence of a specific document. When performing operations such as opening a file or copying resource properties, it is more efficient to simply try the operation and handle failures. If this method returns NO, the optional error is populated. This method is currently applicable only to URLs for file system resources. For other URL types, NO is returned. Symbol is present in iOS 4, but performs no operation. * @return The converted Objective-C result. */ bool check_resource_is_reachable_and_return_error() const; /** * @brief Calls `-[NSURL fileReferenceURL]`. - * @details Returns a file reference URL that refers to the same resource as a specified file URL. File reference URLs use a URL path syntax that identifies a file system object by reference, not by path. This form of file URL remains valid when the file system path of the URL’s underlying resource changes. A file reference URL’s path should never be persistently stored because it is not valid across system restarts and across remounts of volumes. Use a bookmark instead for persistent references. + * @details Returns a file reference URL that refers to the same resource as a specified file URL. File reference URLs use a URL path syntax that identifies a file system object by reference, not by path. This form of file URL remains valid when the file system path of the URL’s underlying resource changes. An error will occur if the url parameter is not a file URL. File reference URLs cannot be created to file system objects which do not exist or are not reachable. In some areas of the file system hierarchy, file reference URLs cannot be generated to the leaf node of the URL path. A file reference URL's path should never be persistently stored because is not valid across system restarts, and across remounts of volumes -- if you want to create a persistent reference to a file system object, use a bookmark (see -bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:). Symbol is present in iOS 4, but performs no operation. * @return The converted Objective-C result. */ URL file_reference_url() const; @@ -186,14 +179,12 @@ namespace cocoon static URL file_url_with_file_system_representation(const std::string& path, bool is_dir, const URL& base_url); /** * @brief Calls `+[NSURL fileURLWithPath:]`. - * @details Initializes and returns a newly created file NSURL referencing the local file or directory at path. Better to use 'fileURLWithPath:isDirectory:' if you know if the path is a directory vs non-directory, as it saves an I/O. * @param path Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URL file_url_with_path(const std::string& path); /** * @brief Calls `+[NSURL fileURLWithPath:isDirectory:]`. - * @details Initializes and returns a newly created file NSURL referencing the local file or directory at path. * @param path Argument converted to the Objective-C parameter of the same role. * @param is_dir Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -210,7 +201,7 @@ namespace cocoon static URL file_url_with_path(const std::string& path, bool is_dir, const URL& base_url); /** * @brief Calls `+[NSURL fileURLWithPath:relativeToURL:]`. - * @details Initializes and returns a newly created file NSURL referencing the local file or directory at path, relative to a base URL. Better to use 'fileURLWithPath:isDirectory:relativeToURL:' if you know if the path is a directory vs non-directory, as it saves an I/O. + * @details Initializes and returns a newly created file NSURL referencing the local file or directory at path, relative to a base URL. * @param path Argument converted to the Objective-C parameter of the same role. * @param base_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -218,14 +209,14 @@ namespace cocoon static URL file_url_with_path(const std::string& path, const URL& base_url); /** * @brief Calls `+[NSURL fileURLWithPathComponents:]`. - * @details Initializes and returns a newly created 'NSURL' object as a file URL with specified path components. The path components are separated by a forward slash in the returned URL. - Parameter components: An array of path components. - Returns: An 'NSURL' object initialized with 'components'. + * @details The following methods work on the path portion of a URL in the same manner that the NSPathUtilities methods on NSString do. * @param components Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URL file_url_with_path_components(const std::vector& components); /** * @brief Calls `-[NSURL getFileSystemRepresentation:maxLength:]`. - * @details Fills a buffer with the URL's path in file system representation. File system representation is a null-terminated C string with canonical UTF-8 encoding. + * @details Returns the URL's path in file system representation. File system representation is a null-terminated C string with canonical UTF-8 encoding. * @param buffer Argument converted to the Objective-C parameter of the same role. * @param max_buffer_length Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -233,13 +224,12 @@ namespace cocoon bool get_file_system_representation(char* buffer, std::uint64_t max_buffer_length) const; /** * @brief Calls `-[NSURL isFileReferenceURL]`. - * @details Returns whether the URL is a file reference URL. + * @details Returns whether the URL is a file reference URL. Symbol is present in iOS 4, but performs no operation. * @return The converted Objective-C result. */ bool is_file_reference_url() const; /** * @brief Calls `-[NSURL promisedItemResourceValuesForKeys:error:]`. - * @details Returns the resource values for the properties identified by specified array of keys from a promised item. This method behaves identically to 'resourceValuesForKeys:error:', but works on promised items. A promised item is not guaranteed to have its contents in the file system until you use a file coordinator to perform a coordinated read on its URL, which causes the contents to be downloaded or otherwise generated. This method works for any resource value that is not tied to the item's contents. Some keys, like 'NSURLContentAccessDateKey' or 'NSURLGenerationIdentifierKey', do not return valid values. - Parameters: - keys: An array of names of URL resource properties. - error: The error that occurred in the case that one or more resource values cannot be retrieved. - Returns: A dictionary of resource values indexed by key. * @param keys Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -251,20 +241,20 @@ namespace cocoon void remove_all_cached_resource_values() const; /** * @brief Calls `-[NSURL removeCachedResourceValueForKey:]`. - * @details Removes the cached resource value identified by a given key from the URL object. Removing a cached resource value may remove other cached resource values because some resource values are cached as a set, and because some resource values depend on other resource values. This method is currently applicable only to URLs for file system resources. + * @details Removes the cached resource value identified by a given resource value key from the URL object. Removing a cached resource value may remove other cached resource values because some resource values are cached as a set of values, and because some resource values depend on other resource values (temporary resource values have no dependencies). This method is currently applicable only to URLs for file system resources. * @param key Argument converted to the Objective-C parameter of the same role. */ void remove_cached_resource_value_for_key(const std::string& key) const; /** * @brief Calls `-[NSURL resourceValuesForKeys:error:]`. - * @details Returns the resource values identified by specified array of resource keys. This method first checks if the URL object already caches the resource values. If so, it returns the cached values. If not, it synchronously obtains the values from the backing store and adds them to the cache. If a resource value for one or more requested keys is not present in the result, that property is not available for the resource. This method is currently applicable only to URLs for file system resources. + * @details Returns the resource values identified by specified array of resource keys. This method first checks if the URL object already caches the resource values. If so, it returns the cached resource values to the caller. If not, then this method synchronously obtains the resource values from the backing store, adds the resource values to the URL object's cache, and returns the resource values to the caller. The type of the resource values vary by property (see resource key definitions). If the result dictionary does not contain a resource value for one or more of the requested resource keys, it means those resource properties are not available for the specified resource and no errors occurred when determining those resource properties were not available. If this method returns NULL, the optional error is populated. This method is currently applicable only to URLs for file system resources. Symbol is present in iOS 4, but performs no operation. * @param keys Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map resource_values_for_keys(const std::vector& keys) const; /** * @brief Calls `+[NSURL resourceValuesForKeys:fromBookmarkData:]`. - * @details Returns the resource values for properties identified by a specified array of keys contained in specified bookmark data. If the result dictionary does not contain a resource value for one or more of the requested resource keys, it means those resource properties are not available in the bookmark data. - Parameters: - keys: An array of names of URL resource properties. In addition to the standard, system-defined resource properties, you can also request any custom properties that you provided when you created the bookmark. - bookmarkData: The bookmark data from which you want to retrieve resource values. - Returns: A dictionary of the requested resource values contained in 'bookmarkData'. + * @details Returns the resource values for properties identified by a specified array of keys contained in specified bookmark data. If the result dictionary does not contain a resource value for one or more of the requested resource keys, it means those resource properties are not available in the bookmark data. * @param keys Argument converted to the Objective-C parameter of the same role. * @param bookmark_data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -272,7 +262,7 @@ namespace cocoon static std::map resource_values_for_keys(const std::vector& keys, const std::vector& bookmark_data); /** * @brief Calls `-[NSURL setResourceValue:forKey:error:]`. - * @details Sets the resource value identified by a given resource key. This method writes the new resource value out to the backing store. Attempts to set a read-only resource property or to set a resource property not supported by the resource are ignored and are not considered errors. This method is currently applicable only to URLs for file system resources. + * @details Sets the resource value identified by a given resource key. This method writes the new resource value out to the backing store. Attempts to set a read-only resource property or to set a resource property not supported by the resource are ignored and are not considered errors. If this method returns NO, the optional error is populated. This method is currently applicable only to URLs for file system resources. Symbol is present in iOS 4, but performs no operation. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -280,32 +270,32 @@ namespace cocoon bool set_resource_value(const Object& value, const std::string& key) const; /** * @brief Calls `-[NSURL setResourceValues:error:]`. - * @details Sets any number of resource values of a URL's resource. This method writes the new resource values out to the backing store. Attempts to set read-only resource properties or to set resource properties not supported by the resource are ignored and are not considered errors. If an error occurs after some resource properties have been successfully changed, the userInfo dictionary in the returned error contains an array of resource keys that were not set with the key 'kCFURLKeysOfUnsetValuesKey'. This method is currently applicable only to URLs for file system resources. + * @details Sets any number of resource values of a URL's resource. This method writes the new resource values out to the backing store. Attempts to set read-only resource properties or to set resource properties not supported by the resource are ignored and are not considered errors. If an error occurs after some resource properties have been successfully changed, the userInfo dictionary in the returned error contains an array of resource keys that were not set with the key kCFURLKeysOfUnsetValuesKey. The order in which the resource values are set is not defined. If you need to guarantee the order resource values are set, you should make multiple requests to this method or to -setResourceValue:forKey:error: to guarantee the order. If this method returns NO, the optional error is populated. This method is currently applicable only to URLs for file system resources. Symbol is present in iOS 4, but performs no operation. * @param keyed_values Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool set_resource_values(const std::map& keyed_values) const; /** * @brief Calls `-[NSURL setTemporaryResourceValue:forKey:]`. - * @details Sets a temporary resource value on the URL object. Temporary resource values are for client use. They exist only in memory and are never written to the resource's backing store. Once set, a temporary resource value can be read with 'getResourceValue:forKey:error:' or 'resourceValuesForKeys:error:'. To remove a temporary resource value, use 'removeCachedResourceValueForKey:'. This method is currently applicable only to URLs for file system resources. + * @details Sets a temporary resource value on the URL object. Temporary resource values are for client use. Temporary resource values exist only in memory and are never written to the resource's backing store. Once set, a temporary resource value can be copied from the URL object with -getResourceValue:forKey:error: or -resourceValuesForKeys:error:. To remove a temporary resource value from the URL object, use -removeCachedResourceValueForKey:. Care should be taken to ensure the key that identifies a temporary resource value is unique and does not conflict with system defined keys (using reverse domain name notation in your temporary resource value keys is recommended). This method is currently applicable only to URLs for file system resources. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void set_temporary_resource_value(const Object& value, const std::string& key) const; /** * @brief Calls `-[NSURL startAccessingSecurityScopedResource]`. - * @details In an app that has adopted App Sandbox, makes the resource pointed to by a security-scoped URL available to the app. When you obtain a security-scoped URL, such as by resolving a security-scoped bookmark, you cannot immediately use the resource it points to. To make the resource available to your app, by way of adding its location to your app's sandbox, call this method on the security-scoped URL. If this method returns 'YES', then you must relinquish access as soon as you finish using the resource by calling ''stopAccessingSecurityScopedResource''. You must balance each call to this method with a corresponding call to ''stopAccessingSecurityScopedResource''. When you make the last balanced call, you immediately lose access to the resource in question. > Warning: If you fail to relinquish your access to file-system resources when you no longer need them, > your app leaks kernel resources. If sufficient kernel resources leak, your app loses its ability to add > file-system locations to its sandbox until relaunched. - Returns: 'YES' if the request to access the resource succeeded; otherwise, 'NO'. + * @details Given a NSURL created by resolving a bookmark data created with security scope, make the resource referenced by the url accessible to the process. Each call to startAccessingSecurityScopedResource that returns YES must be balanced with a call to stopAccessingSecurityScopedResource when access to this resource is no longer needed by the client. Calls to start and stop accessing the resource are reference counted and may be nested, which allows the pair of calls to be logically scoped. * @return The converted Objective-C result. */ bool start_accessing_security_scoped_resource() const; /** * @brief Calls `-[NSURL stopAccessingSecurityScopedResource]`. - * @details In an app that adopts App Sandbox, revokes access to the resource pointed to by a security-scoped URL. When you no longer need access to a file or directory pointed to by a security-scoped URL, such as one returned by resolving a security-scoped bookmark, call this method on the URL to relinquish access. You must balance each call to ''startAccessingSecurityScopedResource'' with a call to this method. When you make the last balanced call, you immediately lose access to the resource in question. If you call this method on a URL whose referenced resource you don't have access to, nothing happens. > Warning: If you fail to relinquish your access to file-system resources when you no longer need them, > your app leaks kernel resources. If sufficient kernel resources leak, your app loses its ability to add > file-system locations to its sandbox until relaunched. + * @details Removes one "accessing" reference to the security scope. When all references are removed, it revokes the access granted to the url by the initial prior successful call to startAccessingSecurityScopedResource. */ void stop_accessing_security_scoped_resource() const; /** * @brief Calls `+[NSURL writeBookmarkData:toURL:options:error:]`. - * @details Creates an alias file on disk at a specified location with specified bookmark data. This method will produce an error if 'bookmarkData' was not created with the 'NSURLBookmarkCreationSuitableForBookmarkFile' option. If 'bookmarkFileURL' points to a directory, the alias file will be created in that directory with its name derived from the information in 'bookmarkData'. If 'bookmarkFileURL' points to a file, the alias file will be created with the location and name indicated by 'bookmarkFileURL', and its extension will be changed to '.alias' if it is not already. - Parameters: - bookmarkData: The bookmark data containing information for the alias file. - bookmarkFileURL: The desired location of the alias file. - options: Options taken into account when creating the alias file. - error: The error that occurred in the case that the alias file cannot be created. - Returns: 'YES' if the alias file is successfully created; otherwise, 'NO'. + * @details Creates an alias file on disk at a specified location with specified bookmark data. bookmarkData must have been created with the NSURLBookmarkCreationSuitableForBookmarkFile option. bookmarkFileURL must either refer to an existing file (which will be overwritten), or to location in an existing directory. If this method returns NO, the optional error is populated. * @param bookmark_data Argument converted to the Objective-C parameter of the same role. * @param bookmark_file_url Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. @@ -319,163 +309,142 @@ namespace cocoon void write_to_pasteboard(const Pasteboard& paste_board) const; /** * @brief Returns the `URLByDeletingLastPathComponent` property of `NSURL`. - * @details A URL you create by removing the last path component from the receiver. If the URL represents the root path, this property contains a copy of the original URL. Otherwise, if the original URL has only one path component, this property contains the empty string. * @return The converted Objective-C result. */ URL url_by_deleting_last_path_component() const; /** * @brief Returns the `URLByDeletingPathExtension` property of `NSURL`. - * @details A URL you create by removing the path extension from the receiver, if any. If the URL represents the root path, this property contains a copy of the original URL. If the URL has multiple path extensions, only the last one is removed. * @return The converted Objective-C result. */ URL url_by_deleting_path_extension() const; /** * @brief Returns the `URLByResolvingSymlinksInPath` property of `NSURL`. - * @details A URL that points to the same resource as the receiver and includes no symbolic links. If the receiver has no symbolic links, this property contains a copy of the original URL. If some symbolic links cannot be resolved, they are left in place. This property only works on URLs with the 'file:' path scheme. For all other URLs, it returns a copy of the receiver. * @return The converted Objective-C result. */ URL url_by_resolving_symlinks_in_path() const; /** * @brief Returns the `URLByStandardizingPath` property of `NSURL`. - * @details A URL that points to the same resource as the original URL using an absolute path. This property only works on URLs with the 'file:' path scheme. For all other URLs, it returns a copy of the original URL. Like ''NSString/standardizingPath'', this property expands an initial tilde expression, reduces empty components and "'/./'" sequences, and resolves "'..'" references in absolute paths. The resulting path may still contain symbolic links. * @return The converted Objective-C result. */ URL url_by_standardizing_path() const; /** * @brief Returns the `absoluteString` property of `NSURL`. - * @details The URL string for the receiver as an absolute URL. * @return The converted Objective-C result. */ std::string absolute_string() const; /** * @brief Returns the `absoluteURL` property of `NSURL`. - * @details The absolute URL. If the receiver is itself absolute, this returns self. * @return The converted Objective-C result. */ URL absolute_url() const; /** * @brief Returns the `baseURL` property of `NSURL`. - * @details The base URL. May be 'nil'. * @return The converted Objective-C result. */ URL base_url() const; /** * @brief Returns the `dataRepresentation` property of `NSURL`. - * @details The data representation of the URL's relativeString. If the URL was initialized with 'initWithData:relativeToURL:', the data representation returned are the same bytes as those used at initialization; otherwise, the data representation returned are the bytes of the relativeString encoded with 'NSUTF8StringEncoding'. + * @details Returns the data representation of the URL's relativeString. If the URL was initialized with -initWithData:relativeToURL:, the data representation returned are the same bytes as those used at initialization; otherwise, the data representation returned are the bytes of the relativeString encoded with NSUTF8StringEncoding. * @return The converted Objective-C result. */ std::vector data_representation() const; /** * @brief Returns the `filePathURL` property of `NSURL`. - * @details A file path URL that refers to the same resource as this URL. File path URLs use a file system style path. The resource must exist and be reachable to be converted. + * @details Returns a file path URL that refers to the same resource as a specified URL. File path URLs use a file system style path. An error will occur if the url parameter is not a file URL. A file reference URL's resource must exist and be reachable to be converted to a file path URL. Symbol is present in iOS 4, but performs no operation. * @return The converted Objective-C result. */ URL file_path_url() const; /** * @brief Returns the `fileSystemRepresentation` property of `NSURL`. - * @details The URL's path in file system representation. File system representation is a null-terminated C string with canonical UTF-8 encoding. The returned C string will be automatically freed just as a returned object would be released; use 'getFileSystemRepresentation:maxLength:' if you need to store the representation outside of the autorelease context. + * @details Returns the URL's path in file system representation. File system representation is a null-terminated C string with canonical UTF-8 encoding. The returned C string will be automatically freed just as a returned object would be released; your code should copy the representation or use getFileSystemRepresentation:maxLength: if it needs to store the representation outside of the autorelease context in which the representation is created. * @return The converted Objective-C result. */ std::string file_system_representation() const; /** * @brief Returns the `fileURL` property of `NSURL`. - * @details A Boolean value that indicates whether the URL scheme is 'file:'. If 'isFileURL' is 'YES', then 'path' is suitable for input into 'NSFileManager' or 'NSPathUtilities'. * @return The converted Objective-C result. */ bool is_file_url() const; /** * @brief Returns the `fragment` property of `NSURL`. - * @details The fragment component of the URL, or 'nil' if the URL does not conform to RFC 1808. * @return The converted Objective-C result. */ std::string fragment() const; /** * @brief Returns the `hasDirectoryPath` property of `NSURL`. - * @details A Boolean value that indicates whether the URL's path represents a directory. Determined from the URL string (whether the path component ends with a '/' character). Does not check the resource. + * @details Determines if a given URL string's path represents a directory (i.e. the path component in the URL string ends with a '/' character). This does not check the resource the URL refers to. * @return The converted Objective-C result. */ bool has_directory_path() const; /** * @brief Returns the `host` property of `NSURL`. - * @details The host component of the URL, or 'nil' if the URL does not conform to RFC 1808. + * @details If the URL conforms to rfc 1808 (the most common form of URL), the following accessors will return the various components; otherwise they return nil. The litmus test for conformance is as recommended in RFC 1808 - whether the first two characters of resourceSpecifier is \@"//". In all cases, they return the component's value after resolving the receiver against its base URL. * @return The converted Objective-C result. */ std::string host() const; /** * @brief Returns the `lastPathComponent` property of `NSURL`. - * @details The last path component. This property contains the last path component, unescaped. For example, in the URL 'file:///path/to/file', the last path component is 'file'. * @return The converted Objective-C result. */ std::string last_path_component() const; /** * @brief Returns the `password` property of `NSURL`. - * @details The password component of the URL, or 'nil' if the URL does not conform to RFC 1808. * @return The converted Objective-C result. */ std::string password() const; /** * @brief Returns the `path` property of `NSURL`. - * @details The path component of the URL, or 'nil' if the URL does not conform to RFC 1808. * @return The converted Objective-C result. */ std::string path() const; /** * @brief Returns the `pathComponents` property of `NSURL`. - * @details An array containing the path components. Each component is unescaped. For example, in the URL 'file:///directory/directory\%202/file', the path components array would be '\@[\@"/", \@"directory", \@"directory 2", \@"file"]'. * @return The converted Objective-C result. */ std::vector path_components() const; /** * @brief Returns the `pathExtension` property of `NSURL`. - * @details The path extension. This property contains the path extension, unescaped. For example, in the URL 'file:///path/to/file.txt', the path extension is 'txt'. * @return The converted Objective-C result. */ std::string path_extension() const; /** * @brief Returns the `port` property of `NSURL`. - * @details The port component of the URL, or 'nil' if the URL does not conform to RFC 1808. * @return The converted Objective-C result. */ Number port() const; /** * @brief Returns the `query` property of `NSURL`. - * @details The query component of the URL, or 'nil' if the URL does not conform to RFC 1808. * @return The converted Objective-C result. */ std::string query() const; /** * @brief Returns the `relativePath` property of `NSURL`. - * @details The relative path of the URL. Same as 'path' if 'baseURL' is 'nil'. * @return The converted Objective-C result. */ std::string relative_path() const; /** * @brief Returns the `relativeString` property of `NSURL`. - * @details The relative portion of the URL. If 'baseURL' is 'nil', or if the receiver is itself absolute, this is the same as 'absoluteString'. * @return The converted Objective-C result. */ std::string relative_string() const; /** * @brief Returns the `resourceSpecifier` property of `NSURL`. - * @details The resource specifier component of the URL. * @return The converted Objective-C result. */ std::string resource_specifier() const; /** * @brief Returns the `scheme` property of `NSURL`. - * @details The scheme component of the URL. The full URL is the concatenation of '[myURL scheme]', '':'', '[myURL resourceSpecifier]'. + * @details Any URL is composed of these two basic pieces. The full URL would be the concatenation of [myURL scheme], ':', [myURL resourceSpecifier] * @return The converted Objective-C result. */ std::string scheme() const; /** * @brief Returns the `standardizedURL` property of `NSURL`. - * @details The standardized form of the URL. * @return The converted Objective-C result. */ URL standardized_url() const; /** * @brief Returns the `user` property of `NSURL`. - * @details The user component of the URL, or 'nil' if the URL does not conform to RFC 1808. * @return The converted Objective-C result. */ std::string user() const; diff --git a/include/generated/url_authentication_challenge.h b/include/generated/url_authentication_challenge.h index 6ca46364..80a4a9f9 100644 --- a/include/generated/url_authentication_challenge.h +++ b/include/generated/url_authentication_challenge.h @@ -15,7 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLAuthenticationChallenge` (Foundation). - * @details A challenge from a server requiring authentication from the client. Your app receives authentication challenges in various ''URLSession'', ''NSURLConnection'', and ''NSURLDownload'' delegate methods, such as ''URLSessionTaskDelegate/urlSession(:task:didReceive:completionHandler:)''. These objects provide the information you'll need when deciding how to handle a server's request for authentication. At the core of that authentication challenge is a protection space that defines the type of authentication being requested, the host and port number, the networking protocol, and (where applicable) the authentication realm (a group of related URLs on the same server that share a single set of credentials). + * @details \@class NSURLAuthenticationChallenge \@discussion This class represents an authentication challenge. It provides all the information about the challenge, and has a method to indicate when it's done. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -41,31 +41,31 @@ namespace cocoon explicit URLAuthenticationChallenge(Adopt adopt); /** * @brief Returns the `error` property of `NSURLAuthenticationChallenge`. - * @details The error representing authentication failure. If there was a previous authentication failure, and this protocol uses errors to indicate authentication failure, then this method will return the error. Otherwise it will return 'nil'. + * @details \@abstract Get the error representing authentication failure. \@discussion If there was a previous authentication failure, and this protocol uses errors to indicate authentication failure, then this method will return the error. Otherwise it will return nil. * @return The converted Objective-C result. */ Error error() const; /** * @brief Returns the `failureResponse` property of `NSURLAuthenticationChallenge`. - * @details The response representing authentication failure. If there was a previous authentication failure, and this protocol uses responses to indicate authentication failure, then this method will return the response. Otherwise it will return 'nil'. + * @details \@abstract Get the response representing authentication failure. \@result The failure response or nil \@discussion If there was a previous authentication failure, and this protocol uses responses to indicate authentication failure, then this method will return the response. Otherwise it will return nil. * @return The converted Objective-C result. */ URLResponse failure_response() const; /** * @brief Returns the `previousFailureCount` property of `NSURLAuthenticationChallenge`. - * @details The count of previous failed authentication attempts. + * @details \@abstract Get count of previous failed authentication attempts \@result The count of previous failures * @return The converted Objective-C result. */ std::int64_t previous_failure_count() const; /** * @brief Returns the `proposedCredential` property of `NSURLAuthenticationChallenge`. - * @details The proposed credential for this challenge. The proposed credential may be 'nil', if there is no default credential to use for this challenge (either stored or in the URL). If the credential is not 'nil' and returns 'YES' for 'hasPassword', it is ready to use as-is. If it returns 'NO' for 'hasPassword', it provides a default username the client could use when prompting. + * @details \@abstract Get the proposed credential for this challenge \@result The proposed credential \@discussion proposedCredential may be nil, if there is no default credential to use for this challenge (either stored or in the URL). If the credential is not nil and returns YES for hasPassword, this means the NSURLConnection thinks the credential is ready to use as-is. If it returns NO for hasPassword, then the credential is not ready to use as-is, but provides a default username the client could use when prompting. * @return The converted Objective-C result. */ URLCredential proposed_credential() const; /** * @brief Returns the `protectionSpace` property of `NSURLAuthenticationChallenge`. - * @details A description of the protection space that requires authentication. + * @details \@abstract Get a description of the protection space that requires authentication \@result The protection space that needs authentication * @return The converted Objective-C result. */ URLProtectionSpace protection_space() const; diff --git a/include/generated/url_cache.h b/include/generated/url_cache.h index e84cf963..994bc7af 100644 --- a/include/generated/url_cache.h +++ b/include/generated/url_cache.h @@ -16,7 +16,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLCache` (Foundation). - * @details An object that maps URL requests to cached response objects. The ''URLCache'' class implements the caching of responses to URL load requests, by mapping ''NSURLRequest'' objects to ''CachedURLResponse'' objects. It provides a composite in-memory and on-disk cache, and lets you manipulate the sizes of both the in-memory and on-disk portions. You can also control the path where cache data is persistently stored. > Note: > In iOS, the on-disk cache may be purged when the system runs low on disk space, but only when your app is not running. \#\#\# Thread safety In iOS 8 and later, and macOS 10.10 and later, ''URLCache'' is thread safe. Although ''URLCache'' instance methods can safely be called from multiple execution contexts at the same time, be aware that methods like ''cachedResponse(for:)'' and ''storeCachedResponse(:for:)-7p7bl'' have an unavoidable race condition when attempting to read or write responses for the same request. Subclasses of ''URLCache'' must implement overridden methods in such a thread-safe manner. \#\#\# Subclassing notes The ''URLCache'' class is meant to be used as-is, but you can subclass it when you have specific needs. For example, you might want to screen which responses are cached, or reimplement the storage mechanism for security or other reasons. When overriding methods of this class, be aware that methods that take a 'task' parameter are preferred by the system to those that do not. Therefore, you should override the task-based methods when subclassing, as follows: - Storing responses in the cache — Override the task-based ''storeCachedResponse(:for:)-8uq91'', instead of or in addition to the request-based ''storeCachedResponse(:for:)-7p7bl''. - Getting responses from the cache — Override ''getCachedResponse(for:completionHandler:)'', instead of or in addition to ''cachedResponse(for:)''. - Removing cached responses — Override the task-based ''removeCachedResponse(for:)-1zwp6'', instead of or in addition to the request-based ''removeCachedResponse(for:)-1dh89''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -58,100 +57,97 @@ namespace cocoon explicit URLCache(Adopt adopt); /** * @brief Calls `-[NSURLCache cachedResponseForRequest:]`. - * @details Returns the cached URL response in the cache for the specified URL request. Returns 'nil' if there is no 'NSCachedURLResponse' stored using the given request. - Parameter request: The 'NSURLRequest' to use as a key for the lookup. - Returns: The 'NSCachedURLResponse' stored in the cache with the given request, or 'nil' if there is no cached response. + * @details \@method cachedResponseForRequest: \@abstract Returns the NSCachedURLResponse stored in the cache with the given request. \@discussion The method returns nil if there is no NSCachedURLResponse stored using the given request. \@param request the NSURLRequest to use as a key for the lookup. \@result The NSCachedURLResponse stored in the cache with the given request, or nil if there is no NSCachedURLResponse stored with the given request. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ CachedURLResponse cached_response_for_request(const URLRequest& request) const; /** * @brief Calls `-[NSURLCache getCachedResponseForDataTask:completionHandler:]`. - * @details Gets the cached URL response for a specified data task, passing it to a completion handler. * @param data_task Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void get_cached_response_for_data_task(const URLSessionDataTask& data_task, std::function completion_handler) const; /** * @brief Calls `-[NSURLCache removeAllCachedResponses]`. - * @details Clears the cache, removing all 'NSCachedURLResponse' objects that it stores. + * @details \@method removeAllCachedResponses \@abstract Clears the given cache, removing all NSCachedURLResponse objects that it stores. */ void remove_all_cached_responses() const; /** * @brief Calls `-[NSURLCache removeCachedResponseForDataTask:]`. - * @details Removes the cached URL response for a specified data task. * @param data_task Argument converted to the Objective-C parameter of the same role. */ void remove_cached_response_for_data_task(const URLSessionDataTask& data_task) const; /** * @brief Calls `-[NSURLCache removeCachedResponseForRequest:]`. - * @details Removes the cached URL response for a specified request. No action is taken if there is no 'NSCachedURLResponse' stored with the given request. - Parameter request: The 'NSURLRequest' to use as a key for the lookup. + * @details \@method removeCachedResponseForRequest: \@abstract Removes the NSCachedURLResponse from the cache that is stored using the given request. \@discussion No action is taken if there is no NSCachedURLResponse stored with the given request. \@param request the NSURLRequest to use as a key for the lookup. * @param request Argument converted to the Objective-C parameter of the same role. */ void remove_cached_response_for_request(const URLRequest& request) const; /** * @brief Calls `-[NSURLCache removeCachedResponsesSinceDate:]`. - * @details Clears the cache of any cached responses since the provided date. + * @details \@method removeCachedResponsesSince: \@abstract Clears the given cache of any cached responses since the provided date. * @param date Argument converted to the Objective-C parameter of the same role. */ void remove_cached_responses_since_date(const Date& date) const; /** * @brief Calls `-[NSURLCache storeCachedResponse:forDataTask:]`. - * @details Stores a cached URL response for a specified data task. * @param cached_response Argument converted to the Objective-C parameter of the same role. * @param data_task Argument converted to the Objective-C parameter of the same role. */ void store_cached_response(const CachedURLResponse& cached_response, const URLSessionDataTask& data_task) const; /** * @brief Calls `-[NSURLCache storeCachedResponse:forRequest:]`. - * @details Stores a cached URL response for a specified request. - Parameters: - cachedResponse: The cached response to store. - request: The 'NSURLRequest' to use as a key for the storage. + * @details \@method storeCachedResponse:forRequest: \@abstract Stores the given NSCachedURLResponse in the cache using the given request. \@param cachedResponse The cached response to store. \@param request the NSURLRequest to use as a key for the storage. * @param cached_response Argument converted to the Objective-C parameter of the same role. * @param request Argument converted to the Objective-C parameter of the same role. */ void store_cached_response(const CachedURLResponse& cached_response, const URLRequest& request) const; /** * @brief Returns the `currentDiskUsage` property of `NSURLCache`. - * @details The current amount of space consumed by the on-disk cache of the receiver, measured in bytes. + * @details \@abstract Returns the current amount of space consumed by the on-disk cache of the receiver. \@discussion This size, measured in bytes, indicates the current usage of the on-disk cache. \@result the current usage of the on-disk cache of the receiver. * @return The converted Objective-C result. */ std::uint64_t current_disk_usage() const; /** * @brief Returns the `currentMemoryUsage` property of `NSURLCache`. - * @details The current amount of space consumed by the in-memory cache of the receiver, measured in bytes. + * @details \@abstract Returns the current amount of space consumed by the in-memory cache of the receiver. \@discussion This size, measured in bytes, indicates the current usage of the in-memory cache. \@result the current usage of the in-memory cache of the receiver. * @return The converted Objective-C result. */ std::uint64_t current_memory_usage() const; /** * @brief Returns the `diskCapacity` property of `NSURLCache`. - * @details The on-disk capacity of the receiver, measured in bytes. On mutation, the on-disk cache will truncate its contents to the size given, if necessary. + * @details \@abstract The on-disk capacity of the receiver. \@discussion The on-disk capacity, measured in bytes, for the receiver. On mutation the on-disk cache will truncate its contents to the size given, if necessary. * @return The converted Objective-C result. */ std::uint64_t disk_capacity() const; /** * @brief Sets the `diskCapacity` property of `NSURLCache`. - * @details The on-disk capacity of the receiver, measured in bytes. On mutation, the on-disk cache will truncate its contents to the size given, if necessary. + * @details \@abstract The on-disk capacity of the receiver. \@discussion The on-disk capacity, measured in bytes, for the receiver. On mutation the on-disk cache will truncate its contents to the size given, if necessary. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_disk_capacity(std::uint64_t value) const; /** * @brief Returns the `memoryCapacity` property of `NSURLCache`. - * @details The in-memory capacity of the receiver, measured in bytes. At the time this value is set, the in-memory cache will truncate its contents to the size given, if necessary. + * @details \@abstract In-memory capacity of the receiver. \@discussion At the time this call is made, the in-memory cache will truncate its contents to the size given, if necessary. \@result The in-memory capacity, measured in bytes, for the receiver. * @return The converted Objective-C result. */ std::uint64_t memory_capacity() const; /** * @brief Sets the `memoryCapacity` property of `NSURLCache`. - * @details The in-memory capacity of the receiver, measured in bytes. At the time this value is set, the in-memory cache will truncate its contents to the size given, if necessary. + * @details \@abstract In-memory capacity of the receiver. \@discussion At the time this call is made, the in-memory cache will truncate its contents to the size given, if necessary. \@result The in-memory capacity, measured in bytes, for the receiver. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_memory_capacity(std::uint64_t value) const; /** * @brief Returns the `sharedURLCache` property of `NSURLCache`. - * @details The shared URL cache instance. Unless set explicitly, this method returns an 'NSURLCache' instance created with the following default values: - Memory capacity: 4 megabytes (4 1024 1024 bytes) - Disk capacity: 20 megabytes (20 1024 1024 bytes) - Disk path: '(user home directory)/Library/Caches/(application bundle id)' If your app doesn't have special caching requirements or constraints, the default shared cache instance should be acceptable. Callers should take care to ensure that the setter is called at a time when no other caller has a reference to the previously-set shared URL cache. + * @details \@property sharedURLCache \@abstract Returns the shared NSURLCache instance or sets the NSURLCache instance shared by all clients of the current process. This will be the new object returned when calls to the \sharedURLCache\ method are made. \@discussion Unless set explicitly through a call to \+setSharedURLCache:\, this method returns an NSURLCache instance created with the following default values: \
    \
  • Memory capacity: 4 megabytes (4 1024 1024 bytes) \
  • Disk capacity: 20 megabytes (20 1024 1024 bytes) \
  • Disk path: \(user home directory)/Library/Caches/(application bundle id)\ \
\

Users who do not have special caching requirements or constraints should find the default shared cache instance acceptable. If this default shared cache instance is not acceptable, \+setSharedURLCache:\ can be called to set a different NSURLCache instance to be returned from this method. Callers should take care to ensure that the setter is called at a time when no other caller has a reference to the previously-set shared URL cache. This is to prevent storing cache data from becoming unexpectedly unretrievable. \@result the shared NSURLCache instance. * @return The converted Objective-C result. */ static URLCache shared_url_cache(); /** * @brief Sets the `sharedURLCache` property of `NSURLCache`. - * @details The shared URL cache instance. Unless set explicitly, this method returns an 'NSURLCache' instance created with the following default values: - Memory capacity: 4 megabytes (4 1024 1024 bytes) - Disk capacity: 20 megabytes (20 1024 1024 bytes) - Disk path: '(user home directory)/Library/Caches/(application bundle id)' If your app doesn't have special caching requirements or constraints, the default shared cache instance should be acceptable. Callers should take care to ensure that the setter is called at a time when no other caller has a reference to the previously-set shared URL cache. + * @details \@property sharedURLCache \@abstract Returns the shared NSURLCache instance or sets the NSURLCache instance shared by all clients of the current process. This will be the new object returned when calls to the \sharedURLCache\ method are made. \@discussion Unless set explicitly through a call to \+setSharedURLCache:\, this method returns an NSURLCache instance created with the following default values: \

    \
  • Memory capacity: 4 megabytes (4 1024 1024 bytes) \
  • Disk capacity: 20 megabytes (20 1024 1024 bytes) \
  • Disk path: \(user home directory)/Library/Caches/(application bundle id)\ \
\

Users who do not have special caching requirements or constraints should find the default shared cache instance acceptable. If this default shared cache instance is not acceptable, \+setSharedURLCache:\ can be called to set a different NSURLCache instance to be returned from this method. Callers should take care to ensure that the setter is called at a time when no other caller has a reference to the previously-set shared URL cache. This is to prevent storing cache data from becoming unexpectedly unretrievable. \@result the shared NSURLCache instance. * @param value Argument converted to the Objective-C parameter of the same role. */ static void set_shared_url_cache(const URLCache& value); diff --git a/include/generated/url_components.h b/include/generated/url_components.h index a7cd0c13..e49f86a0 100644 --- a/include/generated/url_components.h +++ b/include/generated/url_components.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLComponents` (Foundation). - * @details An object that parses URLs into and constructs URLs from their constituent parts. In Swift, this object bridges to ''URLComponents''; use ''NSURLComponents'' when you need reference semantics or other Foundation-specific behavior. The ''NSURLComponents'' class is a class that is designed to parse URLs based on [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt) and to construct URLs from their constituent parts. Its behavior differs subtly from the ''NSURL'' class, which conforms to older RFCs. However, you can easily obtain an ''NSURL'' object based on the contents of a URL components object or vice versa. You create a URL components object in one of three ways: from an ''NSString'' object that contains a URL, from an ''NSURL'' object, or from scratch by using the default initializer. From there, you can modify the URL's individual components and subcomponents by modifying various properties, either in unencoded form or in URL-encoded form. If you set the unencoded property, you can then obtain the encoded equivalent by reading the encoded property value and vice versa. > Important: > The Swift overlay to the Foundation framework provides the ''URLComponents'' structure, which bridges to the ''NSURLComponents'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -58,14 +57,12 @@ namespace cocoon explicit URLComponents(Adopt adopt); /** * @brief Calls `-[NSURLComponents URLRelativeToURL:]`. - * @details Returns a URL object derived from the components object, relative to a base URL. If the components object has an authority component (user, password, host, or port) and a path component, then the path must either begin with '"/"' or be an empty string. Otherwise, this method returns 'nil'. If the components object does not have an authority component (user, password, host, or port) and has a path component, the path component must not start with '"//"'. If it does, this method returns 'nil'. - Parameter baseURL: If non-'nil', this URL is used as the base URL portion of the resulting URL object. * @param base_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URL url_relative_to_url(const URL& base_url) const; /** * @brief Calls `+[NSURLComponents componentsWithString:]`. - * @details Returns a URL components object by parsing a URL in string form. - Parameter URLString: The URL string to parse. - Returns: Returns the new URL components object, or 'nil' if the URL string could not be parsed. * @param url_string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -80,7 +77,6 @@ namespace cocoon static URLComponents components_with_string(const std::string& url_string, bool encoding_invalid_characters); /** * @brief Calls `+[NSURLComponents componentsWithURL:resolvingAgainstBaseURL:]`. - * @details Returns a URL components object by parsing the URL from an 'NSURL' object. - Parameters: - url: The URL to parse. - resolve: Controls whether the URL should be resolved against its base URL before parsing. If 'YES', and if the 'url' parameter contains a relative URL, the original URL is resolved against its base URL before parsing by calling the 'absoluteURL' method. Otherwise, the string portion is used by itself. - Returns: Returns the new URL components object, or 'nil' if the URL could not be parsed. * @param url Argument converted to the Objective-C parameter of the same role. * @param resolve Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -88,127 +84,106 @@ namespace cocoon static URLComponents components_with_url(const URL& url, bool resolve); /** * @brief Returns the `URL` property of `NSURLComponents`. - * @details A URL object derived from the components object. If the receiver has an authority component (user, password, host, or port) and a path component, then the path must either begin with '"/"' or be an empty string. Otherwise, this property contains 'nil'. If the receiver does not have an authority component (user, password, host, or port) and has a path component, the path component must not start with '"//"'. If it does, this property contains 'nil'. * @return The converted Objective-C result. */ URL url() const; /** * @brief Returns the `encodedHost` property of `NSURLComponents`. - * @details The host subcomponent, percent-encoded. The getter for this property retains any percent-encoding this component may have. Setting this property assumes the component string already has the correct percent-encoding. Attempting to set an incorrectly percent-encoded string raises an exception. * @return The converted Objective-C result. */ std::string encoded_host() const; /** * @brief Sets the `encodedHost` property of `NSURLComponents`. - * @details The host subcomponent, percent-encoded. The getter for this property retains any percent-encoding this component may have. Setting this property assumes the component string already has the correct percent-encoding. Attempting to set an incorrectly percent-encoded string raises an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_encoded_host(const std::string& value) const; /** * @brief Returns the `fragment` property of `NSURLComponents`. - * @details The fragment URL component (the part after a '\#' symbol), or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html\#jumpLocation', the fragment is 'jumpLocation'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @return The converted Objective-C result. */ std::string fragment() const; /** * @brief Sets the `fragment` property of `NSURLComponents`. - * @details The fragment URL component (the part after a '\#' symbol), or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html\#jumpLocation', the fragment is 'jumpLocation'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_fragment(const std::string& value) const; /** * @brief Returns the `host` property of `NSURLComponents`. - * @details The host URL subcomponent, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html', the host is 'www.example.com'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @return The converted Objective-C result. */ std::string host() const; /** * @brief Sets the `host` property of `NSURLComponents`. - * @details The host URL subcomponent, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html', the host is 'www.example.com'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_host(const std::string& value) const; /** * @brief Returns the `password` property of `NSURLComponents`. - * @details The password URL subcomponent, or 'nil' if not present. For example, in the URL 'http://username:password\@www.example.com/index.html', the password is 'password'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @return The converted Objective-C result. */ std::string password() const; /** * @brief Sets the `password` property of `NSURLComponents`. - * @details The password URL subcomponent, or 'nil' if not present. For example, in the URL 'http://username:password\@www.example.com/index.html', the password is 'password'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_password(const std::string& value) const; /** * @brief Returns the `path` property of `NSURLComponents`. - * @details The path URL component, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html', the path is '/index.html'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @return The converted Objective-C result. */ std::string path() const; /** * @brief Sets the `path` property of `NSURLComponents`. - * @details The path URL component, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html', the path is '/index.html'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_path(const std::string& value) const; /** * @brief Returns the `percentEncodedFragment` property of `NSURLComponents`. - * @details The fragment URL component (the part after a '\#' symbol) expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @return The converted Objective-C result. */ std::string percent_encoded_fragment() const; /** * @brief Sets the `percentEncodedFragment` property of `NSURLComponents`. - * @details The fragment URL component (the part after a '\#' symbol) expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_percent_encoded_fragment(const std::string& value) const; /** * @brief Returns the `percentEncodedHost` property of `NSURLComponents`. - * @details The host URL subcomponent expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @return The converted Objective-C result. */ std::string percent_encoded_host() const; /** * @brief Sets the `percentEncodedHost` property of `NSURLComponents`. - * @details The host URL subcomponent expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_percent_encoded_host(const std::string& value) const; /** * @brief Returns the `percentEncodedPassword` property of `NSURLComponents`. - * @details The password URL subcomponent expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @return The converted Objective-C result. */ std::string percent_encoded_password() const; /** * @brief Sets the `percentEncodedPassword` property of `NSURLComponents`. - * @details The password URL subcomponent expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_percent_encoded_password(const std::string& value) const; /** * @brief Returns the `percentEncodedPath` property of `NSURLComponents`. - * @details The path URL component expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. Although an unencoded semicolon is a valid character in a percent-encoded path, for compatibility with 'NSURL', you should always percent-encode it. * @return The converted Objective-C result. */ std::string percent_encoded_path() const; /** * @brief Sets the `percentEncodedPath` property of `NSURLComponents`. - * @details The path URL component expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. Although an unencoded semicolon is a valid character in a percent-encoded path, for compatibility with 'NSURL', you should always percent-encode it. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_percent_encoded_path(const std::string& value) const; /** * @brief Returns the `percentEncodedQuery` property of `NSURLComponents`. - * @details The query URL component expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @return The converted Objective-C result. */ std::string percent_encoded_query() const; /** * @brief Sets the `percentEncodedQuery` property of `NSURLComponents`. - * @details The query URL component expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_percent_encoded_query(const std::string& value) const; @@ -224,127 +199,107 @@ namespace cocoon void set_percent_encoded_query_items(const std::vector& value) const; /** * @brief Returns the `percentEncodedUser` property of `NSURLComponents`. - * @details The username URL subcomponent expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @return The converted Objective-C result. */ std::string percent_encoded_user() const; /** * @brief Sets the `percentEncodedUser` property of `NSURLComponents`. - * @details The username URL subcomponent expressed as a URL-encoded string, or 'nil' if not present. If you set this value to something that is not a valid, percent-encoded string, this class throws an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_percent_encoded_user(const std::string& value) const; /** * @brief Returns the `port` property of `NSURLComponents`. - * @details The port number URL component, or 'nil' if not present. For example, in the URL 'http://www.example.com:8080/index.php', the port number is '8080'. Attempting to set a negative port number will cause an exception. * @return The converted Objective-C result. */ Number port() const; /** * @brief Sets the `port` property of `NSURLComponents`. - * @details The port number URL component, or 'nil' if not present. For example, in the URL 'http://www.example.com:8080/index.php', the port number is '8080'. Attempting to set a negative port number will cause an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_port(const Number& value) const; /** * @brief Returns the `query` property of `NSURLComponents`. - * @details The query URL component as a string, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.php?key1=value1&key2=value2', the query string is 'key1=value1&key2=value2'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @return The converted Objective-C result. */ std::string query() const; /** * @brief Sets the `query` property of `NSURLComponents`. - * @details The query URL component as a string, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.php?key1=value1&key2=value2', the query string is 'key1=value1&key2=value2'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_query(const std::string& value) const; /** * @brief Returns the `queryItems` property of `NSURLComponents`. - * @details The query URL component as an array of name/value pairs. When you get this property's value, the 'NSURLComponents' class parses the 'query' string and returns an array of 'NSURLQueryItem' objects, each of which represents a single key-value pair, in the order in which they appear in the original query string. Because a name may appear more than once in a single query string, the name properties of query items are not guaranteed to be unique. If the 'query' property is an empty string, the 'queryItems' property is an empty array. If the 'query' property is 'nil', the 'queryItems' property is also 'nil'. When you set this property's value, the 'NSURLComponents' class joins each name/value pair with a '=' delimiter and joins the array with a '&' delimiter, then sets the 'query' property to the resulting string. Setting this property to an empty array sets the 'query' property to an empty string. Setting this property to 'nil' sets the 'query' property to 'nil'. * @return The converted Objective-C result. */ std::vector query_items() const; /** * @brief Sets the `queryItems` property of `NSURLComponents`. - * @details The query URL component as an array of name/value pairs. When you get this property's value, the 'NSURLComponents' class parses the 'query' string and returns an array of 'NSURLQueryItem' objects, each of which represents a single key-value pair, in the order in which they appear in the original query string. Because a name may appear more than once in a single query string, the name properties of query items are not guaranteed to be unique. If the 'query' property is an empty string, the 'queryItems' property is an empty array. If the 'query' property is 'nil', the 'queryItems' property is also 'nil'. When you set this property's value, the 'NSURLComponents' class joins each name/value pair with a '=' delimiter and joins the array with a '&' delimiter, then sets the 'query' property to the resulting string. Setting this property to an empty array sets the 'query' property to an empty string. Setting this property to 'nil' sets the 'query' property to 'nil'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_query_items(const std::vector& value) const; /** * @brief Returns the `rangeOfFragment` property of `NSURLComponents`. - * @details Returns the character range of the fragment in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. * @return The converted Objective-C result. */ Range range_of_fragment() const; /** * @brief Returns the `rangeOfHost` property of `NSURLComponents`. - * @details Returns the character range of the host in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. * @return The converted Objective-C result. */ Range range_of_host() const; /** * @brief Returns the `rangeOfPassword` property of `NSURLComponents`. - * @details Returns the character range of the password in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. * @return The converted Objective-C result. */ Range range_of_password() const; /** * @brief Returns the `rangeOfPath` property of `NSURLComponents`. - * @details Returns the character range of the path in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. * @return The converted Objective-C result. */ Range range_of_path() const; /** * @brief Returns the `rangeOfPort` property of `NSURLComponents`. - * @details Returns the character range of the port in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. * @return The converted Objective-C result. */ Range range_of_port() const; /** * @brief Returns the `rangeOfQuery` property of `NSURLComponents`. - * @details Returns the character range of the query in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. * @return The converted Objective-C result. */ Range range_of_query() const; /** * @brief Returns the `rangeOfScheme` property of `NSURLComponents`. - * @details Returns the character range of the scheme in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. + * @details These properties return the character range of a component in the URL string returned by -[NSURLComponents string]. If the component does not exist in the NSURLComponents object, {NSNotFound, 0} is returned. Note: Zero length components are legal. For example, the URL string "scheme://:\@/?\#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path. * @return The converted Objective-C result. */ Range range_of_scheme() const; /** * @brief Returns the `rangeOfUser` property of `NSURLComponents`. - * @details Returns the character range of the user in the URL string returned by the 'string' property. If the component does not exist in the 'NSURLComponents' object, '{NSNotFound, 0}' is returned. * @return The converted Objective-C result. */ Range range_of_user() const; /** * @brief Returns the `scheme` property of `NSURLComponents`. - * @details The scheme URL component, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html', the scheme is 'http'. Attempting to set the scheme with an invalid scheme string will cause an exception. * @return The converted Objective-C result. */ std::string scheme() const; /** * @brief Sets the `scheme` property of `NSURLComponents`. - * @details The scheme URL component, or 'nil' if not present. For example, in the URL 'http://www.example.com/index.html', the scheme is 'http'. Attempting to set the scheme with an invalid scheme string will cause an exception. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_scheme(const std::string& value) const; /** * @brief Returns the `string` property of `NSURLComponents`. - * @details A URL derived from the components object, in string form. If the receiver has an authority component (user, password, host, or port) and a path component, then the path must either begin with '"/"' or be an empty string. Otherwise, this property contains 'nil'. If the receiver does not have an authority component (user, password, host, or port) and has a path component, the path component must not start with '"//"'. If it does, this property contains 'nil'. * @return The converted Objective-C result. */ std::string string() const; /** * @brief Returns the `user` property of `NSURLComponents`. - * @details The username URL subcomponent, or 'nil' if not present. For example, in the URL 'http://username:password\@www.example.com/index.html', the user is 'username'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @return The converted Objective-C result. */ std::string user() const; /** * @brief Sets the `user` property of `NSURLComponents`. - * @details The username URL subcomponent, or 'nil' if not present. For example, in the URL 'http://username:password\@www.example.com/index.html', the user is 'username'. Getting this property removes any percent encoding this component may have. Setting this property assumes the string is not percent encoded and will add percent encoding. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_user(const std::string& value) const; diff --git a/include/generated/url_connection.h b/include/generated/url_connection.h index 564bc0dd..4da9205b 100644 --- a/include/generated/url_connection.h +++ b/include/generated/url_connection.h @@ -16,7 +16,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLConnection` (Foundation). - * @details An object that enables you to start and stop URL requests. > Important: > This API is considered legacy. Use ''URLSession'' instead. An 'NSURLConnection' object lets you load the contents of a URL by providing a URL request object. The interface for 'NSURLConnection' is sparse, providing only the controls to start and cancel asynchronous loads of a URL request. You perform most of your configuration on the URL request object itself. > Note: > Although instances of this class are commonly called "connections", there is not a 1:1 correlation between these objects and the underlying network connections. The 'NSURLConnection' class provides convenience class methods to load URL requests both asynchronously using a callback block and synchronously. For greater control, you can create a URL connection object with a delegate object that conforms to the ''NSURLConnectionDelegate'' and ''NSURLConnectionDataDelegate'' protocols. The connection calls methods on that delegate to provide you with progress and status as the URL request is loaded asynchronously. The connection also calls delegate methods to let you override the connection's default behavior (for example, specifying how a particular redirect should be handled). These delegate methods are called on the thread that initiated the asynchronous load operation. > Note: > During a request, the connection maintains a strong reference to its delegate. It releases that strong reference when the connection finishes loading, fails, or is canceled. For more information about errors, see the 'NSURLError.h' header, \, and URL Loading System Error Codes in [Error Handling Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ErrorHandlingCocoa/ErrorHandling/ErrorHandling.html\#//apple_ref/doc/uid/TP40001806). \#\#\# NSURLConnection Protocols The 'NSURLConnection' class works in tandem with three formal protocols: ''NSURLConnectionDelegate'', ''NSURLConnectionDataDelegate'', and ''NSURLConnectionDownloadDelegate''. To use these protocols, you write a class that conforms to them and implement any methods that are appropriate, then provide an instance of that class as the delegate when you create a connection object. The ''NSURLConnectionDelegate'' protocol is primarily used for credential handling, but also handles connection completion. Because it handles connection failure during data transfers, all connection delegates must typically implement this protocol. In addition, unless you're using Newsstand Kit, your delegate must also conform to the ''NSURLConnectionDataDelegate'' protocol, because this protocol provides methods that the 'NSURLConnection' class calls with progress information during an upload, with fragments of the response data during a download, and to provide a new upload body stream if the server's response necessitates a second connection attempt—for example, if 'NSURLConnection' must retry the request with different credentials. Finally, if you're using Newsstand Kit, your delegate can conform to the ''NSURLConnectionDownloadDelegate'' protocol. This protocol provides support for continuing interrupted file downloads and receiving a notification whenever a download finishes. This protocol is solely for use with 'NSURLConnection' objects created using Newsstand Kit's 'download(with:)' method. > Note: > Some methods in these protocols were previously part of other formal protocols or were previously part of an informal protocol on 'NSObject'. + * @details \@class NSURLConnection \@abstract An NSURLConnection object provides support to perform asynchronous loads of a URL request, providing data to a client supplied delegate. \@discussion The interface for NSURLConnection is very sparse, providing only the controls to start and cancel asynchronous loads of a URL request.\

An NSURLConnection may be used for loading of resource data directly to memory, in which case an NSURLConnectionDataDelegate should be supplied, or for downloading of resource data directly to a file, in which case an NSURLConnectionDownloadDelegate is used. The delegate is retained by the NSURLConnection until a terminal condition is encountered. These two delegates are logically subclasses of the base protocol, NSURLConnectionDelegate.\

A terminal condition produced by the loader will result in a connection:didFailWithError: in the case of an error, or connectionDidFinishLoading: or connectionDidFinishDownloading: delegate message.\

The -cancel message hints to the loader that a resource load should be abandoned but does not guarantee that more delegate messages will not be delivered. If -cancel does cause the load to be abandoned, the delegate will be released without further messages. In general, a caller should be prepared for -cancel to have no effect, and internally ignore any delegate callbacks until the delegate is released. Scheduling of an NSURLConnection specifies the context in which delegate callbacks will be made, but the actual IO may occur on a separate thread and should be considered an implementation detail.\

When created, an NSURLConnection performs a deep-copy of the NSURLRequest. This copy is available through the -originalRequest method. As the connection performs the load, this request may change as a result of protocol canonicalization or due to following redirects. -currentRequest can be used to retrieve this value.\

An NSURLConnections created with the +connectionWithRequest:delegate: or -initWithRequest:delegate: methods are scheduled on the current runloop immediately, and it is not necessary to send the -start message to begin the resource load.\

NSURLConnections created with -initWithRequest:delegate:startImmediately: are not automatically scheduled. Use -scheduleWithRunLoop:forMode: or -setDelegateQueue: to specify the context for delegate callbacks, and -start to begin the load. If you do not explicitly schedule the connection before -start, it will be scheduled on the current runloop and mode automatically.\

The NSURLConnectionSynchronousLoading category adds +sendSynchronousRequest:returningResponse:error, which blocks the current thread until the resource data is available or an error occurs. It should be noted that using this method on an applications main run loop may result in an unacceptably long delay in a user interface and its use is strongly discourage.\

The NSURLConnectionQueuedLoading category implements +sendAsynchronousRequest:queue:completionHandler, providing similar simplicity but provides a mechanism where the current runloop is not blocked.\

Both of the immediate loading categories do not provide for customization of resource load, and do not allow the caller to respond to, e.g., authentication challenges.\

* Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -47,19 +47,17 @@ namespace cocoon explicit URLConnection(Adopt adopt); /** * @brief Calls `+[NSURLConnection canHandleRequest:]`. - * @details Returns whether a request can be handled based on a preflight evaluation. The result of this method is valid as long as no ''NSURLProtocol'' classes are registered or unregistered, and 'request' remains unchanged. Applications should be prepared to handle failures even if they have performed request preflighting by calling this method. - Parameter request: The request to evaluate. The connection deep-copies the request on creation. - Returns: 'YES' if a preflight operation determines that a connection with 'request' can be created and the associated I/O can be started, 'NO' otherwise. + * @details \@method canHandleRequest: \@abstract Performs a "preflight" operation that performs some speculative checks to see if a connection can be initialized, and the associated I/O that is started in the initializer methods can begin. \@discussion The result of this method is valid only as long as no protocols are registered or unregistered, and as long as the request is not mutated (if the request is mutable). Hence, clients should be prepared to handle failures even if they have performed request preflighting by calling this method. \@param request The request to preflight. \@result YES if it is likely that the given request can be used to initialize a connection and the associated I/O can be started, NO otherwise. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool can_handle_request(const URLRequest& request); /** * @brief Calls `-[NSURLConnection cancel]`. - * @details Cancels an asynchronous load of a request. After this method is called, the connection makes no further delegate method calls. If you want to reattempt the connection, you should create a new connection object. */ void cancel() const; /** * @brief Calls `-[NSURLConnection scheduleInRunLoop:forMode:]`. - * @details Determines the run loop and mode that the connection uses to call methods on its delegate. By default, a connection is scheduled on the current thread in the default mode when it is created. You cannot reschedule a connection after it has started. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ @@ -74,7 +72,7 @@ namespace cocoon static void send_asynchronous_request(const URLRequest& request, const OperationQueue& queue, std::function, Error)> handler); /** * @brief Calls `+[NSURLConnection sendSynchronousRequest:returningResponse:error:]`. - * @details Performs a synchronous load of the specified URL request. A synchronous load is built on top of the asynchronous loading code made available by the class. The calling thread is blocked while the asynchronous loading system performs the URL load on a thread spawned specifically for this load request. No special threading or run loop configuration is necessary in the calling thread in order to perform a synchronous load. > Important: Because this call can potentially take several minutes to complete (particularly when using a cellular network in iOS), you should never call this function from the main thread of your application. The solution is to migrate to URL loading using ''NSURLSession''. If authentication is required in order to download the request, the required credentials must be specified as part of the URL. If authentication fails, or credentials are missing, the connection will attempt to continue without credentials. - Parameters: - request: The URL request to load. The 'request' object is deep-copied as part of the initialization process. Changes made to 'request' after this method returns do not affect the request that is used for the loading process. - response: Out parameter for the URL response returned by the server. - error: Out parameter used if an error occurs while processing the request. May be 'NULL'. - Returns: The downloaded data for the URL request. Returns 'nil' if a connection could not be created or if the download fails. + * @details \@method sendSynchronousRequest:returningResponse:error: \@abstract Performs a synchronous load of the given request, returning an NSURLResponse in the given out parameter. \@discussion A synchronous load for the given request is built on top of the asynchronous loading code made available by the class. The calling thread is blocked while the asynchronous loading system performs the URL load on a thread spawned specifically for this load request. No special threading or run loop configuration is necessary in the calling thread in order to perform a synchronous load. For instance, the calling thread need not be running its run loop. \@param request The request to load. Note that the request is deep-copied as part of the initialization process. Changes made to the request argument after this method returns do not affect the request that is used for the loading process. \@param response An out parameter which is filled in with the response generated by performing the load. \@param error Out parameter (may be NULL) used if an error occurs while processing the request. Will not be modified if the load succeeds. \@result The content of the URL resulting from performing the load, or nil if the load failed. * @param request Argument converted to the Objective-C parameter of the same role. * @param response Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -82,31 +80,26 @@ namespace cocoon static std::vector send_synchronous_request(const URLRequest& request, URLResponse& response); /** * @brief Calls `-[NSURLConnection setDelegateQueue:]`. - * @details Determines the operation queue that is used to call methods on the connection's delegate. By default, a connection is scheduled on the current thread in the default mode when it is created. You cannot reschedule a connection after it has started. * @param queue Argument converted to the Objective-C parameter of the same role. */ void set_delegate_queue(const OperationQueue& queue) const; /** * @brief Calls `-[NSURLConnection start]`. - * @details Causes the connection to begin loading data, if it has not already. Calling this method is necessary only if you create a connection with the '-initWithRequest:delegate:startImmediately:' method and provide 'NO' for the 'startImmediately' parameter. If you don't schedule the connection in a run loop or an operation queue before calling this method, the connection is scheduled in the current run loop in the default mode. */ void start() const; /** * @brief Calls `-[NSURLConnection unscheduleFromRunLoop:forMode:]`. - * @details Removes the connection from the specified run loop and mode. * @param a_run_loop Argument converted to the Objective-C parameter of the same role. * @param mode Argument converted to the Objective-C parameter of the same role. */ void unschedule_from_run_loop(const RunLoop& a_run_loop, const std::string& mode) const; /** * @brief Returns the `currentRequest` property of `NSURLConnection`. - * @details The current connection request. As the connection performs the load, the request may change as a result of protocol canonicalization or due to following redirects. This property provides the current value of the request. * @return The converted Objective-C result. */ URLRequest current_request() const; /** * @brief Returns the `originalRequest` property of `NSURLConnection`. - * @details A deep copy of the original connection request. As the connection performs the load, the request may change as a result of protocol canonicalization or due to following redirects. * @return The converted Objective-C result. */ URLRequest original_request() const; diff --git a/include/generated/url_credential.h b/include/generated/url_credential.h index e17941ec..364a50cc 100644 --- a/include/generated/url_credential.h +++ b/include/generated/url_credential.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLCredential` (Foundation). - * @details An authentication credential consisting of information specific to the type of credential and the type of persistent storage to use, if any. The URL Loading System supports password-based user credentials, certificate-based user credentials, and certificate-based server credentials. When you create a credential, you can specify it for a single request, persist it temporarily (until your app quits), or persist it permanently. Permanent persistence can be local persistence in the keychain, or synchronized persistence across the user's devices, based on their Apple ID. > Note: > Permanent storage of credentials is only available for password-based credentials. TLS credentials are never stored permanently by ''URLCredentialStorage''. In general, use for-session persistence for TLS credentials. + * @details \@class NSURLCredential \@discussion This class is an immutable object representing an authentication credential. The actual type of the credential is determined by the constructor called in the categories declared below. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,14 +48,14 @@ namespace cocoon explicit URLCredential(Adopt adopt); /** * @brief Calls `+[NSURLCredential credentialForTrust:]`. - * @details Creates a URL credential instance for server trust authentication with a given accepted trust. Before creating a server trust credential, it is the responsibility of the delegate of an ''NSURLConnection'' instance or an ''NSURLDownload'' instance to evaluate the trust. Do this by calling 'SecTrustEvaluate', passing it the trust obtained from the 'serverTrust' method of the server's ''NSURLProtectionSpace'' instance. If the trust is invalid, the authentication challenge should be cancelled with the ''NSURLAuthenticationChallengeSender'' protocol's 'cancelAuthenticationChallenge:' method. - Parameter trust: The accepted trust. - Returns: A new URL credential object, containing the accepted server trust. + * @details \@method credentialForTrust: \@abstract Create a new NSURLCredential which specifies that a handshake has been trusted. \@result The new autoreleased NSURLCredential * @param trust Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URLCredential credential_for_trust(const SecTrust& trust); /** * @brief Calls `+[NSURLCredential credentialWithIdentity:certificates:persistence:]`. - * @details Creates a new 'NSURLCredential' with an identity and certificate array. - Parameter identity: A 'SecIdentityRef' object. - Parameter certArray: An array containing at least one 'SecCertificateRef' objects. - Parameter persistence: A value indicating whether the credential should be stored permanently, for the duration of the current session, or not at all. - Returns: The new autoreleased 'NSURLCredential'. + * @details \@method credentialWithIdentity:certificates:persistence: \@abstract Create a new NSURLCredential with an identity and certificate array \@param identity a SecIdentityRef object \@param certArray an array containing at least one SecCertificateRef objects \@param persistence enum that says to store per session, permanently or not at all \@result The new autoreleased NSURLCredential * @param identity Argument converted to the Objective-C parameter of the same role. * @param cert_array Argument converted to the Objective-C parameter of the same role. * @param persistence Argument converted to the Objective-C parameter of the same role. @@ -64,7 +64,7 @@ namespace cocoon static URLCredential credential_with_identity(const SecIdentity& identity, const std::vector& cert_array, URLCredentialPersistence persistence); /** * @brief Calls `+[NSURLCredential credentialWithUser:password:persistence:]`. - * @details Creates a new 'NSURLCredential' with a user and password. - Parameter user: The user for the credential. - Parameter password: The password for 'user'. - Parameter persistence: A value indicating whether the credential should be stored permanently, for the duration of the current session, or not at all. - Returns: The new autoreleased 'NSURLCredential'. + * @details \@method credentialWithUser:password:persistence: \@abstract Create a new NSURLCredential with a user and password \@param user the username \@param password the password \@param persistence enum that says to store per session, permanently or not at all \@result The new autoreleased NSURLCredential * @param user Argument converted to the Objective-C parameter of the same role. * @param password Argument converted to the Objective-C parameter of the same role. * @param persistence Argument converted to the Objective-C parameter of the same role. @@ -73,37 +73,37 @@ namespace cocoon static URLCredential credential_with_user(const std::string& user, const std::string& password, URLCredentialPersistence persistence); /** * @brief Returns the `certificates` property of `NSURLCredential`. - * @details The intermediate certificates of the credential, if it is a client certificate credential. The certificates are 'SecCertificateRef' objects. This value is 'nil' if this is not a client certificate credential. + * @details \@abstract Returns an NSArray of SecCertificateRef objects representing the client certificate for this credential, if this credential was created with an identity and certificate. \@result an NSArray of SecCertificateRef or NULL if this is a username/password credential * @return The converted Objective-C result. */ std::vector certificates() const; /** * @brief Returns the `hasPassword` property of `NSURLCredential`. - * @details A Boolean value that indicates whether the credential has a password. This method does not attempt to retrieve the password. If this credential's password is stored in the user's keychain, the 'password' property may return 'nil' even if this method returns 'YES' -- getting the password may fail, or the user may refuse access. + * @details \@abstract Find out if this credential has a password, without trying to get it \@result YES if this credential has a password, otherwise NO \@discussion If this credential's password is actually kept in an external store, the password method may return nil even if this method returns YES, since getting the password may fail, or the user may refuse access. * @return The converted Objective-C result. */ bool has_password() const; /** * @brief Returns the `identity` property of `NSURLCredential`. - * @details The identity of this credential if it is a client certificate credential. This value is 'nil' if the credential is not a client certificate credential. + * @details \@abstract Returns the SecIdentityRef of this credential, if it was created with a certificate and identity \@result A SecIdentityRef or NULL if this is a username/password credential * @return The converted Objective-C result. */ SecIdentity identity() const; /** * @brief Returns the `password` property of `NSURLCredential`. - * @details The credential's password. You should only access this property if you need the actual password value. If you only need to know if there is a password, use 'hasPassword'. Accessing this property may result in prompting the user for access. + * @details \@abstract Get the password \@result The password string \@discussion This method might actually attempt to retrieve the password from an external store, possible resulting in prompting, so do not call it unless needed. * @return The converted Objective-C result. */ std::string password() const; /** * @brief Returns the `persistence` property of `NSURLCredential`. - * @details The credential's persistence setting. + * @details \@abstract Determine whether this credential is or should be stored persistently \@result A value indicating whether this credential is stored permanently, per session or not at all. * @return The converted Objective-C result. */ URLCredentialPersistence persistence() const; /** * @brief Returns the `user` property of `NSURLCredential`. - * @details The credential's user name. + * @details \@abstract Get the username \@result The user string * @return The converted Objective-C result. */ std::string user() const; diff --git a/include/generated/url_credential_storage.h b/include/generated/url_credential_storage.h index 46a446da..2f853502 100644 --- a/include/generated/url_credential_storage.h +++ b/include/generated/url_credential_storage.h @@ -14,7 +14,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLCredentialStorage` (Foundation). - * @details The manager of a shared credentials cache. The shared cache stores and retrieves instances of ''URLCredential''. You can store password-based credentials permanently, based on the ''URLCredential/Persistence'' they were created with. Certificate-based credentials are never stored permanently. \#\#\# Subclassing notes The ''URLCredentialStorage'' class is meant to be used as-is, but you can subclass it if you have specific needs, such as screening which credentials are stored. When overriding methods of this class, be aware that methods that take a 'task' parameter are preferred to equivalent methods that do not. Therefore, you should override the task-based methods when subclassing, as follows: - Setting credentials — Override ''set(:for:task:)'' instead of or in addition to ''set(:for:)''. - Getting credentials — Override ''getCredentials(for:task:completionHandler:)'' instead of or in addition to ''credentials(for:)''. - Removing credentials — Override ''remove(:for:options:task:)'' instead of or in addition to ''remove(:for:options:)'' and ''remove(:for:)''. - Setting default credentials — Override ''setDefaultCredential(:for:task:)'' instead of or in addition to ''setDefaultCredential(:for:)''. - Getting default credentials — Override ''getDefaultCredential(for:task:completionHandler:)'' instead of or in addition to ''defaultCredential(for:)''. + * @details \@class NSURLCredentialStorage \@discussion NSURLCredentialStorage implements a singleton object (shared instance) which manages the shared credentials cache. Note: Whereas in Mac OS X any application can access any credential with a persistence of NSURLCredentialPersistencePermanent provided the user gives permission, in iPhone OS an application can access only its own credentials. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,21 +45,20 @@ namespace cocoon explicit URLCredentialStorage(Adopt adopt); /** * @brief Calls `-[NSURLCredentialStorage credentialsForProtectionSpace:]`. - * @details Gets a dictionary mapping usernames to credentials for the specified protection space. - Parameter space: An 'NSURLProtectionSpace' indicating the protection space for which to get credentials. - Returns: A dictionary where the keys are usernames and the values are the corresponding 'NSURLCredential' instances. + * @details \@method credentialsForProtectionSpace: \@abstract Get a dictionary mapping usernames to credentials for the specified protection space. \@param space An NSURLProtectionSpace indicating the protection space for which to get credentials \@result A dictionary where the keys are usernames and the values are the corresponding NSURLCredentials. * @param space Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map credentials_for_protection_space(const URLProtectionSpace& space) const; /** * @brief Calls `-[NSURLCredentialStorage defaultCredentialForProtectionSpace:]`. - * @details Gets the default credential for the specified protection space. - Parameter space: The protection space for which to get the default credential. + * @details \@method defaultCredentialForProtectionSpace: \@abstract Get the default credential for the specified protection space. \@param space The protection space for which to get the default credential. * @param space Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLCredential default_credential_for_protection_space(const URLProtectionSpace& space) const; /** * @brief Calls `-[NSURLCredentialStorage getCredentialsForProtectionSpace:task:completionHandler:]`. - * @details Fetches credentials for the specified protection space and task, passing them to the completion handler. * @param protection_space Argument converted to the Objective-C parameter of the same role. * @param task Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. @@ -67,7 +66,6 @@ namespace cocoon void get_credentials_for_protection_space(const URLProtectionSpace& protection_space, const URLSessionTask& task, std::function)> completion_handler) const; /** * @brief Calls `-[NSURLCredentialStorage getDefaultCredentialForProtectionSpace:task:completionHandler:]`. - * @details Fetches the default credential for the specified protection space and task, passing it to the completion handler. * @param space Argument converted to the Objective-C parameter of the same role. * @param task Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. @@ -75,14 +73,14 @@ namespace cocoon void get_default_credential_for_protection_space(const URLProtectionSpace& space, const URLSessionTask& task, std::function completion_handler) const; /** * @brief Calls `-[NSURLCredentialStorage removeCredential:forProtectionSpace:]`. - * @details Removes the credential from the set for the specified protection space. - Parameter credential: The credential to remove. - Parameter space: The protection space for which a credential should be removed. The credential is removed from both persistent and temporary storage. A credential that has a persistence policy of 'NSURLCredentialPersistenceSynchronizable' will fail. See 'removeCredential:forProtectionSpace:options:'. + * @details \@method removeCredential:forProtectionSpace: \@abstract Remove the credential from the set for the specified protection space. \@param credential The credential to remove. \@param space The protection space for which a credential should be removed \@discussion The credential is removed from both persistent and temporary storage. A credential that has a persistence policy of NSURLCredentialPersistenceSynchronizable will fail. See removeCredential:forProtectionSpace:options. * @param credential Argument converted to the Objective-C parameter of the same role. * @param space Argument converted to the Objective-C parameter of the same role. */ void remove_credential(const URLCredential& credential, const URLProtectionSpace& space) const; /** * @brief Calls `-[NSURLCredentialStorage removeCredential:forProtectionSpace:options:]`. - * @details Removes the credential from the set for the specified protection space based on options. - Parameter credential: The credential to remove. - Parameter space: The protection space for which a credential should be removed. - Parameter options: A dictionary containing options to consider when removing the credential. This should be used when trying to delete a credential that has the 'NSURLCredentialPersistenceSynchronizable' policy. When such credentials are removed, the credential will be removed on all devices that contain this credential. The credential is removed from both persistent and temporary storage. + * @details \@method removeCredential:forProtectionSpace:options \@abstract Remove the credential from the set for the specified protection space based on options. \@param credential The credential to remove. \@param space The protection space for which a credential should be removed \@param options A dictionary containing options to consider when removing the credential. This should be used when trying to delete a credential that has the NSURLCredentialPersistenceSynchronizable policy. Please note that when NSURLCredential objects that have a NSURLCredentialPersistenceSynchronizable policy are removed, the credential will be removed on all devices that contain this credential. \@discussion The credential is removed from both persistent and temporary storage. * @param credential Argument converted to the Objective-C parameter of the same role. * @param space Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. @@ -90,7 +88,6 @@ namespace cocoon void remove_credential(const URLCredential& credential, const URLProtectionSpace& space, const std::map& options) const; /** * @brief Calls `-[NSURLCredentialStorage removeCredential:forProtectionSpace:options:task:]`. - * @details Removes a credential for the specified protection space, options, and task. * @param credential Argument converted to the Objective-C parameter of the same role. * @param protection_space Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. @@ -99,14 +96,13 @@ namespace cocoon void remove_credential(const URLCredential& credential, const URLProtectionSpace& protection_space, const std::map& options, const URLSessionTask& task) const; /** * @brief Calls `-[NSURLCredentialStorage setCredential:forProtectionSpace:]`. - * @details Adds a new credential to the set for the specified protection space or replaces an existing one. - Parameter credential: The credential to set. - Parameter space: The protection space for which to add it. Multiple credentials may be set for a given protection space, but each must have a distinct user. If a credential with the same user is already set for the protection space, the new one will replace it. + * @details \@method setCredential:forProtectionSpace: \@abstract Add a new credential to the set for the specified protection space or replace an existing one. \@param credential The credential to set. \@param space The protection space for which to add it. \@discussion Multiple credentials may be set for a given protection space, but each must have a distinct user. If a credential with the same user is already set for the protection space, the new one will replace it. * @param credential Argument converted to the Objective-C parameter of the same role. * @param space Argument converted to the Objective-C parameter of the same role. */ void set_credential(const URLCredential& credential, const URLProtectionSpace& space) const; /** * @brief Calls `-[NSURLCredentialStorage setCredential:forProtectionSpace:task:]`. - * @details Sets a credential for the specified protection space and task. * @param credential Argument converted to the Objective-C parameter of the same role. * @param protection_space Argument converted to the Objective-C parameter of the same role. * @param task Argument converted to the Objective-C parameter of the same role. @@ -114,14 +110,13 @@ namespace cocoon void set_credential(const URLCredential& credential, const URLProtectionSpace& protection_space, const URLSessionTask& task) const; /** * @brief Calls `-[NSURLCredentialStorage setDefaultCredential:forProtectionSpace:]`. - * @details Sets the default credential for the specified protection space. - Parameter credential: The credential to set as default. - Parameter space: The protection space for which the credential should be set as default. If the credential is not yet in the set for the protection space, it will be added to it. + * @details \@method setDefaultCredential:forProtectionSpace: \@abstract Set the default credential for the specified protection space. \@param credential The credential to set as default. \@param space The protection space for which the credential should be set as default. \@discussion If the credential is not yet in the set for the protection space, it will be added to it. * @param credential Argument converted to the Objective-C parameter of the same role. * @param space Argument converted to the Objective-C parameter of the same role. */ void set_default_credential(const URLCredential& credential, const URLProtectionSpace& space) const; /** * @brief Calls `-[NSURLCredentialStorage setDefaultCredential:forProtectionSpace:task:]`. - * @details Sets the default credential for the specified protection space and task. * @param credential Argument converted to the Objective-C parameter of the same role. * @param protection_space Argument converted to the Objective-C parameter of the same role. * @param task Argument converted to the Objective-C parameter of the same role. @@ -129,13 +124,13 @@ namespace cocoon void set_default_credential(const URLCredential& credential, const URLProtectionSpace& protection_space, const URLSessionTask& task) const; /** * @brief Returns the `allCredentials` property of `NSURLCredentialStorage`. - * @details The credentials for all available protection spaces. The dictionary has keys corresponding to 'NSURLProtectionSpace' instances. The values are dictionaries where the keys are user name strings, and each value is the corresponding 'NSURLCredential' instance. + * @details \@abstract Get a dictionary mapping NSURLProtectionSpaces to dictionaries which map usernames to NSURLCredentials \@result an NSDictionary where the keys are NSURLProtectionSpaces and the values are dictionaries, in which the keys are usernames and the values are NSURLCredentials * @return The converted Objective-C result. */ std::vector>> all_credentials() const; /** * @brief Returns the `sharedCredentialStorage` property of `NSURLCredentialStorage`. - * @details The shared singleton authentication storage. + * @details \@property sharedCredentialStorage \@abstract Get the shared singleton authentication storage \@result the shared authentication storage * @return The converted Objective-C result. */ static URLCredentialStorage shared_credential_storage(); diff --git a/include/generated/url_download.h b/include/generated/url_download.h index c1512caa..e17a4c30 100644 --- a/include/generated/url_download.h +++ b/include/generated/url_download.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLDownload` (Foundation). - * @details An object that downloads a resource asynchronously and saves the data to a file. > Important: > This API is considered legacy. Use ''URLSession'' instead. The interface for ''NSURLDownload'' provides methods to initialize a download, set the destination path and cancel loading the request. The delegate object assigned to each instance of this class should implement the methods defined by the ''NSURLDownloadDelegate'' protocol. These methods provide the delegate with the current status of in-progress asynchronous downloads and allow the delegate to customize the URL loading process. These delegate methods are called on the thread that started the asynchronous load operation for the associated ''NSURLDownload'' object. + * @details \@class NSURLDownload \@discussion A NSURLDownload loads a request and saves the downloaded data to a file. The progress of the download is reported via the NSURLDownloadDelegate protocol. Note: The word "download" is used to refer to the process of loading data off a network, decoding the data if necessary and saving the data to a file. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,44 +45,44 @@ namespace cocoon explicit URLDownload(Adopt adopt); /** * @brief Calls `+[NSURLDownload canResumeDownloadDecodedWithEncodingMIMEType:]`. - * @details Returns whether a URL download object can resume a download that was decoded with the specified MIME type. The MIME type of a file, in conjunction with the value returned by the 'download:shouldDecodeSourceDataOfMIMEType:' delegate method, determines whether the 'NSURLDownload' class should decode or decompress the incoming data as it is received. Some compression techniques, such as the 'DEFLATE' algorithm ('gzip') use symbol dictionaries that vary during the compression process, making it impractical to decompress only a portion of the data starting in the middle. For this reason, this method returns 'NO' unless both of the following conditions are met: - The MIME type is of a type that the 'NSURLDownload' class knows how to decompress or decode. - The decoding can be safely resumed. In practice, this method returns 'YES' for MacBinary and BinHex, otherwise 'NO'. If your app needs to be able to resume file downloads in 'gzip' format, your 'download:shouldDecodeSourceDataOfMIMEType:' method must return 'NO', and you must decode the resulting file yourself after you finish downloading it in its entirety. - Parameter MIMEType: The MIME type the caller wants to know about. - Returns: 'YES' if the URL download object can resume a download that was decoded with the specified MIME type, 'NO' otherwise. + * @details \@method canResumeDownloadDecodedWithEncodingMIMEType: \@abstract Returns whether or not NSURLDownload can resume a download that was decoded with a given encoding MIME type. \@param MIMEType The encoding MIME type. \@description canResumeDownloadDecodedWithEncodingMIMEType: returns whether or not NSURLDownload can resume a download that was decoded with a given encoding MIME type. NSURLDownload cannot resume a download that was partially decoded in the gzip format for example. In order to ensure that a download can be later resumed, canResumeDownloadDecodedWithEncodingMIMEType: should be used when download:shouldDecodeSourceDataOfMIMEType: is called. * @param mime_type Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool can_resume_download_decoded_with_encoding_mime_type(const std::string& mime_type); /** * @brief Calls `-[NSURLDownload cancel]`. - * @details Cancels the receiver's download and deletes the downloaded file. This method deletes the partially downloaded file unless you have previously called ''deletesFileUponFailure'', passing 'NO'. + * @details \@method cancel \@abstract Cancels the download and deletes the downloaded file. */ void cancel() const; /** * @brief Calls `-[NSURLDownload setDestination:allowOverwrite:]`. - * @details Sets the destination path of the downloaded file. If 'allowOverwrite' is 'NO' and a file already exists at 'path', a unique filename will be created by appending a number to the filename. The delegate can implement ''NSURLDownloadDelegate/download(:didCreateDestination:)'' to determine the filename used when the file is written to disk. An 'NSURLDownload' instance ignores multiple calls to this method. - Parameters: - path: The path for the downloaded file. - allowOverwrite: 'YES' if an existing file at 'path' can be replaced, 'NO' otherwise. + * @details \@method setDestination:allowOverwrite: \@abstract Sets the destination path of the downloaded file. \@param path The destination path of the downloaded file. \@param allowOverwrite Allows a file of the same path to be overwritten. \@discussion This method can be called after the download is created or in response to the decideDestinationWithSuggestedFilename: delegate method. It should only be called once. If NO is passed for allowOverwrite and a file of the same path exists, a number will be appended to the filename to prevent the overwrite. Because of this, use the path passed with didCreateDestination: to determine the actual path of the downloaded file. * @param path Argument converted to the Objective-C parameter of the same role. * @param allow_overwrite Argument converted to the Objective-C parameter of the same role. */ void set_destination(const std::string& path, bool allow_overwrite) const; /** * @brief Returns the `deletesFileUponFailure` property of `NSURLDownload`. - * @details Whether the receiver deletes partially downloaded files when a download stops prematurely. The default value is 'YES'. To allow the download to be resumed in case the download ends prematurely, set this property to 'NO' as soon as possible to prevent the downloaded file from being deleted. + * @details \@abstract Sets whether or not the downloaded file should be deleted upon failure. 1 \@description To allow the download to be resumed in case the download ends prematurely, deletesFileUponFailure must be set to NO as soon as possible to prevent the downloaded file from being deleted. deletesFileUponFailure is YES by default. * @return The converted Objective-C result. */ bool deletes_file_upon_failure() const; /** * @brief Sets the `deletesFileUponFailure` property of `NSURLDownload`. - * @details Whether the receiver deletes partially downloaded files when a download stops prematurely. The default value is 'YES'. To allow the download to be resumed in case the download ends prematurely, set this property to 'NO' as soon as possible to prevent the downloaded file from being deleted. + * @details \@abstract Sets whether or not the downloaded file should be deleted upon failure. 1 \@description To allow the download to be resumed in case the download ends prematurely, deletesFileUponFailure must be set to NO as soon as possible to prevent the downloaded file from being deleted. deletesFileUponFailure is YES by default. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_deletes_file_upon_failure(bool value) const; /** * @brief Returns the `request` property of `NSURLDownload`. - * @details The URL request that initiated the receiver's download. + * @details \@abstract Returns the request of the download. \@result The request of the download. * @return The converted Objective-C result. */ URLRequest request() const; /** * @brief Returns the `resumeData` property of `NSURLDownload`. - * @details The resume data for a download that is not yet complete. This data represents the necessary state information that an 'NSURLDownload' object needs to resume a download. The resume data can later be used when initializing a download with 'initWithResumeData:delegate:path:'. Returns 'nil' if the download is not able to be resumed. Resume data is returned only if both the protocol and the server support resuming. + * @details \@abstract Returns the resume data of a download that is incomplete. \@result The resume data. \@description resumeData returns the resume data of a download that is incomplete. This data represents the necessary state information that NSURLDownload needs to resume a download. The resume data can later be used when initializing a download with initWithResumeData:delegate:path:. Non-nil is returned if resuming the download seems possible. Non-nil is returned if the download was cancelled or ended in error after some but not all data has been received. The protocol of the download as well as the server must support resuming for non-nil to be returned. In order to later resume a download, be sure to call setDeletesFileUponFailure: with NO. * @return The converted Objective-C result. */ std::vector resume_data() const; diff --git a/include/generated/url_handle.h b/include/generated/url_handle.h index 0716c2d2..8c5723a9 100644 --- a/include/generated/url_handle.h +++ b/include/generated/url_handle.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSURLHandle` (Foundation). - * @details An object that accesses and manages resource data indicated by a URL. > Important: > ''NSURLHandle'' is deprecated in macOS 10.4 and later. Use ''URLSession'' instead. A single ''NSURLHandle'' can service multiple equivalent ''NSURL'' objects, but only if these URLs map to the same resource. Cocoa provides private concrete subclasses to handle HTTP and file URL schemes. If you want to implement support for additional URL schemes, you would do so by creating a subclass of 'NSURLHandle'. You can use 'NSURL' and 'NSURLHandle' to download from FTP sites without subclassing. \@DeprecationSummary { Use ''URLSession'' instead. } * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example diff --git a/include/generated/url_protection_space.h b/include/generated/url_protection_space.h index d59df023..b009e823 100644 --- a/include/generated/url_protection_space.h +++ b/include/generated/url_protection_space.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLProtectionSpace` (Foundation). - * @details A server or an area on a server, commonly referred to as a realm, that requires authentication. A protection space defines a series of matching constraints that determine which credential should be provided. For example, if a request provides your delegate with a ''URLAuthenticationChallenge'' object that requests a client username and password, your app should provide the correct username and password for the particular host, port, protocol, and realm, as specified in the challenge's protection space. > Note: > This class has no designated initializer; its 'init' method always returns 'nil'. You must initialize this class by calling one of the initialization methods described in Creating a protection space. + * @details \@class NSURLProtectionSpace \@discussion This class represents a protection space requiring authentication. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -36,61 +36,61 @@ namespace cocoon explicit URLProtectionSpace(Adopt adopt); /** * @brief Returns the `authenticationMethod` property of `NSURLProtectionSpace`. - * @details The authentication method used by the receiver. + * @details \@abstract Get the authentication method to be used for this protection space \@result The authentication method * @return The converted Objective-C result. */ std::string authentication_method() const; /** * @brief Returns the `distinguishedNames` property of `NSURLProtectionSpace`. - * @details The acceptable certificate-issuing authorities for client certificate authentication. Issuers are identified by their distinguished name and returned as DER encoded data. This value is 'nil' if the authentication method is not 'NSURLAuthenticationMethodClientCertificate'. + * @details \@abstract Returns an array of acceptable certificate issuing authorities for client certification authentication. Issuers are identified by their distinguished name and returned as a DER encoded data. \@result An array of NSData objects. (Nil if the authenticationMethod is not NSURLAuthenticationMethodClientCertificate) * @return The converted Objective-C result. */ std::vector> distinguished_names() const; /** * @brief Returns the `host` property of `NSURLProtectionSpace`. - * @details The receiver's host. + * @details \@abstract Get the proxy host if this is a proxy authentication, or the host from the URL. \@result The host for this protection space. * @return The converted Objective-C result. */ std::string host() const; /** * @brief Returns the `isProxy` property of `NSURLProtectionSpace`. - * @details A Boolean value that indicates whether this authenticating protection space is a proxy server. + * @details \@abstract Determine if this authenticating protection space is a proxy server \@result YES if a proxy, NO otherwise * @return The converted Objective-C result. */ bool is_proxy() const; /** * @brief Returns the `port` property of `NSURLProtectionSpace`. - * @details The receiver's port. + * @details \@abstract Get the proxy port if this is a proxy authentication, or the port from the URL. \@result The port for this protection space, or 0 if not set. * @return The converted Objective-C result. */ std::int64_t port() const; /** * @brief Returns the `protocol` property of `NSURLProtectionSpace`. - * @details The receiver's protocol. This value is 'nil' if the receiver represents a proxy protection space. + * @details \@abstract Get the protocol of this protection space, if not a proxy \@result The type string, or nil if a proxy. * @return The converted Objective-C result. */ std::string protocol() const; /** * @brief Returns the `proxyType` property of `NSURLProtectionSpace`. - * @details The receiver's proxy type. This value is 'nil' if the receiver does not represent a proxy protection space. + * @details \@abstract Get the type of this protection space, if a proxy \@result The type string, or nil if not a proxy. * @return The converted Objective-C result. */ std::string proxy_type() const; /** * @brief Returns the `realm` property of `NSURLProtectionSpace`. - * @details The receiver's authentication realm. This value is 'nil' if no realm has been set. A realm is generally only specified for HTTP and HTTPS authentication. + * @details \@abstract Get the authentication realm for which the protection space that needs authentication \@discussion This is generally only available for http authentication, and may be nil otherwise. \@result The realm string * @return The converted Objective-C result. */ std::string realm() const; /** * @brief Returns the `receivesCredentialSecurely` property of `NSURLProtectionSpace`. - * @details A Boolean value that indicates whether the credentials for the protection space can be sent securely. + * @details \@abstract Determine if the password for this protection space can be sent securely \@result YES if a secure authentication method or protocol will be used, NO otherwise * @return The converted Objective-C result. */ bool receives_credential_securely() const; /** * @brief Returns the `serverTrust` property of `NSURLProtectionSpace`. - * @details A representation of the server's SSL transaction state. This value is 'nil' if the authentication method is not 'NSURLAuthenticationMethodServerTrust'. + * @details \@abstract Returns a SecTrustRef which represents the state of the servers SSL transaction state \@result A SecTrustRef from Security.framework. (Nil if the authenticationMethod is not NSURLAuthenticationMethodServerTrust) * @return The converted Objective-C result. */ SecTrust server_trust() const; diff --git a/include/generated/url_protocol.h b/include/generated/url_protocol.h index 586c1c15..a40b4d5b 100644 --- a/include/generated/url_protocol.h +++ b/include/generated/url_protocol.h @@ -15,7 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLProtocol` (Foundation). - * @details An abstract class that handles the loading of protocol-specific URL data. Don't instantiate a ''URLProtocol'' subclass directly. Instead, create subclasses for any custom protocols or URL schemes that your app supports. When a download starts, the system creates the appropriate protocol object to handle the corresponding URL request. You define your protocol class and call the ''registerClass(:)'' class method during your app's launch time so that the system is aware of your protocol. > Note: > You cannot use this class to define custom URL schemes and protocols in watchOS 2 and later. To support the customization of protocol-specific requests, create extensions to the ''URLRequest'' class to provide any custom API that you need. You can store and retrieve protocol-specific request data by using ''URLProtocol'''s class methods ''property(forKey:in:)'' and ''setProperty(:forKey:in:)''. Create a ''URLResponse'' for each request your subclass processes successfully. You may want to create a custom ''URLResponse'' class to provide protocol specific information. \#\#\# Subclassing notes When overriding methods of this class, be aware that methods that take a 'task' parameter are preferred by the system to those that do not. Therefore, you should override the task-based methods when subclassing, as follows: Swift: - Initialization — Override ''init(task:cachedResponse:client:)'' instead of or in addition to ''init(request:cachedResponse:client:)''. Also override the task-based ''canInit(with:)-18gbo'' instead of or in addition to the request-based ''canInit(with:)-76brg''. Objective-C: - Initialization — Override ''canInit(with:)-18gbo'' and ''init(task:cachedResponse:client:)'' instead of or in addition to ''canInit(with:)-76brg'' and ''init(request:cachedResponse:client:)''. + * @details \@class NSURLProtocol \@abstract NSURLProtocol is an abstract class which provides the basic structure for performing protocol-specific loading of URL data. Concrete subclasses handle the specifics associated with one or more protocols or URL schemes. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -49,28 +49,27 @@ namespace cocoon explicit URLProtocol(Adopt adopt); /** * @brief Calls `+[NSURLProtocol canInitWithRequest:]`. - * @details Determines whether the protocol subclass can handle the specified request. A concrete subclass should inspect the given request and determine whether or not the implementation can perform a load with that request. This is an abstract method. Subclasses must provide an implementation. - Parameter request: A request to inspect. - Returns: 'YES' if the protocol can handle the given request, 'NO' if not. + * @details \@method canInitWithRequest: \@abstract This method determines whether this protocol can handle the given request. \@discussion A concrete subclass should inspect the given request and determine whether or not the implementation can perform a load with that request. This is an abstract method. Subclasses must provide an implementation. \@param request A request to inspect. \@result YES if the protocol can handle the given request, NO if not. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool can_init_with_request(const URLRequest& request); /** * @brief Calls `+[NSURLProtocol canInitWithTask:]`. - * @details Determines whether the protocol subclass can handle the specified task. * @param task Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool can_init_with_task(const URLSessionTask& task); /** * @brief Calls `+[NSURLProtocol canonicalRequestForRequest:]`. - * @details Returns a canonical version of the specified request. It is up to each concrete protocol implementation to define what "canonical" means. However, a protocol should guarantee that the same input request always yields the same canonical form. Special consideration should be given when implementing this method since the canonical form of a request is used to look up objects in the URL cache, a process which performs equality checks between 'NSURLRequest' objects. This is an abstract method; subclasses must provide an implementation. - Parameter request: A request to make canonical. - Returns: The canonical form of the given request. + * @details \@method canonicalRequestForRequest: \@abstract This method returns a canonical version of the given request. \@discussion It is up to each concrete protocol implementation to define what "canonical" means. However, a protocol should guarantee that the same input request always yields the same canonical form. Special consideration should be given when implementing this method since the canonical form of a request is used to look up objects in the URL cache, a process which performs equality checks between NSURLRequest objects. \

This is an abstract method; subclasses must provide an implementation. \@param request A request to make canonical. \@result The canonical form of the given request. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URLRequest canonical_request_for_request(const URLRequest& request); /** * @brief Calls `+[NSURLProtocol propertyForKey:inRequest:]`. - * @details Fetches the property associated with the specified key in the specified request. The purpose of this method is to provide an interface for protocol implementors to access protocol-specific information associated with 'NSURLRequest' objects. - Parameters: - key: The string to use for the property lookup. - request: The request to use for the property lookup. - Returns: The property stored with the given key, or 'nil' if no property had previously been stored with the given key in the given request. + * @details \@method propertyForKey:inRequest: \@abstract Returns the property in the given request previously stored with the given key. \@discussion The purpose of this method is to provide an interface for protocol implementors to access protocol-specific information associated with NSURLRequest objects. \@param key The string to use for the property lookup. \@param request The request to use for the property lookup. \@result The property stored with the given key, or nil if no property had previously been stored with the given key in the given request. * @param key Argument converted to the Objective-C parameter of the same role. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -78,21 +77,21 @@ namespace cocoon static Object property_for_key(const std::string& key, const URLRequest& request); /** * @brief Calls `+[NSURLProtocol registerClass:]`. - * @details Attempts to register a subclass of ''URLProtocol'', making it visible to the URL loading system. When the URL loading system begins to load a request, each protocol class that has been registered is consulted in turn to see if it can be initialized with a given request. The first protocol handler class to provide a 'YES' answer to '+canInitWithRequest:' "wins" and that protocol implementation is used to perform the URL load. There is no guarantee that all registered protocol classes will be consulted. Registering a class places it first on the list of classes that will be consulted. - Parameter protocolClass: The class to register. - Returns: 'YES' if the protocol was registered successfully, 'NO' if not. The only way that failure can occur is if the given class is not a subclass of 'NSURLProtocol'. + * @details \@method registerClass: \@abstract This method registers a protocol class, making it visible to several other NSURLProtocol class methods. \@discussion When the URL loading system begins to load a request, each protocol class that has been registered is consulted in turn to see if it can be initialized with a given request. The first protocol handler class to provide a YES answer to \+canInitWithRequest:\ "wins" and that protocol implementation is used to perform the URL load. There is no guarantee that all registered protocol classes will be consulted. Hence, it should be noted that registering a class places it first on the list of classes that will be consulted in calls to \+canInitWithRequest:\, moving it in front of all classes that had been registered previously. \

A similar design governs the process to create the canonical form of a request with the \+canonicalRequestForRequest:\ class method. \@param protocolClass the class to register. \@result YES if the protocol was registered successfully, NO if not. The only way that failure can occur is if the given class is not a subclass of NSURLProtocol. * @param protocol_class Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static bool register_class(const std::string& protocol_class); /** * @brief Calls `+[NSURLProtocol removePropertyForKey:inRequest:]`. - * @details Removes the property associated with the specified key in the specified request. Like 'setProperty:forKey:inRequest:', the purpose of this method is to give protocol implementors the ability to store protocol-specific information in an 'NSURLRequest'. - Parameters: - key: The key whose value should be removed. - request: The request to be modified. + * @details \@method removePropertyForKey:inRequest: \@abstract Remove any property stored under the given key \@discussion Like setProperty:forKey:inRequest: above, the purpose of this method is to give protocol implementors the ability to store protocol-specific information in an NSURLRequest \@param key The key whose value should be removed \@param request The request to be modified * @param key Argument converted to the Objective-C parameter of the same role. * @param request Argument converted to the Objective-C parameter of the same role. */ static void remove_property_for_key(const std::string& key, const MutableURLRequest& request); /** * @brief Calls `+[NSURLProtocol requestIsCacheEquivalent:toRequest:]`. - * @details A Boolean value indicating whether two requests are equivalent for cache purposes. Requests are considered equivalent for cache purposes if and only if they would be handled by the same protocol AND that protocol declares them equivalent after performing implementation-specific checks. - Returns: 'YES' if the two requests are cache-equivalent, 'NO' otherwise. + * @details \@method requestIsCacheEquivalent:toRequest: \@abstract Compares two requests for equivalence with regard to caching. \@discussion Requests are considered equivalent for cache purposes if and only if they would be handled by the same protocol AND that protocol declares them equivalent after performing implementation-specific checks. \@result YES if the two requests are cache-equivalent, NO otherwise. * @param a Argument converted to the Objective-C parameter of the same role. * @param b Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -100,7 +99,7 @@ namespace cocoon static bool request_is_cache_equivalent(const URLRequest& a, const URLRequest& b); /** * @brief Calls `+[NSURLProtocol setProperty:forKey:inRequest:]`. - * @details Sets the property associated with the specified key in the specified request. The purpose of this method is to provide an interface for protocol implementors to customize protocol-specific information associated with 'NSMutableURLRequest' objects. - Parameters: - value: The property to store. - key: The string to use for the property storage. - request: The request in which to store the property. + * @details \@method setProperty:forKey:inRequest: \@abstract Stores the given property in the given request using the given key. \@discussion The purpose of this method is to provide an interface for protocol implementors to customize protocol-specific information associated with NSMutableURLRequest objects. \@param value The property to store. \@param key The string to use for the property storage. \@param request The request in which to store the property. * @param value Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. * @param request Argument converted to the Objective-C parameter of the same role. @@ -108,35 +107,34 @@ namespace cocoon static void set_property(const Object& value, const std::string& key, const MutableURLRequest& request); /** * @brief Calls `-[NSURLProtocol startLoading]`. - * @details Starts protocol-specific loading of the request. When this method is called, the protocol implementation should start loading a request. + * @details \@method startLoading \@abstract Starts protocol-specific loading of a request. \@discussion When this method is called, the protocol implementation should start loading a request. */ void start_loading() const; /** * @brief Calls `-[NSURLProtocol stopLoading]`. - * @details Stops protocol-specific loading of the request. When this method is called, the protocol implementation should end the work of loading a request. This could be in response to a cancel operation, so protocol implementations must be able to handle this call while a load is in progress. + * @details \@method stopLoading \@abstract Stops protocol-specific loading of a request. \@discussion When this method is called, the protocol implementation should end the work of loading a request. This could be in response to a cancel operation, so protocol implementations must be able to handle this call while a load is in progress. */ void stop_loading() const; /** * @brief Calls `+[NSURLProtocol unregisterClass:]`. - * @details Unregisters the specified subclass of ''URLProtocol''. After unregistration, a protocol class is no longer consulted in calls to 'NSURLProtocol' class methods. - Parameter protocolClass: The class to unregister. + * @details \@method unregisterClass: \@abstract This method unregisters a protocol. \@discussion After unregistration, a protocol class is no longer consulted in calls to NSURLProtocol class methods. \@param protocolClass The class to unregister. * @param protocol_class Argument converted to the Objective-C parameter of the same role. */ static void unregister_class(const std::string& protocol_class); /** * @brief Returns the `cachedResponse` property of `NSURLProtocol`. - * @details The protocol's cached response. + * @details \@abstract Returns the NSCachedURLResponse of the receiver. \@result The NSCachedURLResponse of the receiver. * @return The converted Objective-C result. */ CachedURLResponse cached_response() const; /** * @brief Returns the `request` property of `NSURLProtocol`. - * @details The protocol's request. + * @details \@abstract Returns the NSURLRequest of the receiver. \@result The NSURLRequest of the receiver. * @return The converted Objective-C result. */ URLRequest request() const; /** * @brief Returns the `task` property of `NSURLProtocol`. - * @details The protocol's task. * @return The converted Objective-C result. */ URLSessionTask task() const; diff --git a/include/generated/url_query_item.h b/include/generated/url_query_item.h index 8bbfaf82..8f08e8bb 100644 --- a/include/generated/url_query_item.h +++ b/include/generated/url_query_item.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSURLQueryItem` (Foundation). - * @details An object representing a single name/value pair for an item in the query portion of a URL. In Swift, this object bridges to ''URLQueryItem''; use ''NSURLQueryItem'' when you need reference semantics or other Foundation-specific behavior. You use query items with the ''NSURLComponents/queryItems'' property of an ''NSURLComponents'' object. > Important: > The Swift overlay to the Foundation framework provides the ''URLQueryItem'' structure, which bridges to the ''NSURLQueryItem'' class. For more information about value types, see \. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -41,7 +40,6 @@ namespace cocoon explicit URLQueryItem(Adopt adopt); /** * @brief Calls `+[NSURLQueryItem queryItemWithName:value:]`. - * @details Creates a new query item with the specified name and value. To use the newly initialized query item in composing a URL, add it to the ''NSURLComponents/queryItems'' array of an ''NSURLComponents'' instance. Because assigning an array of query items to an ''NSURLComponents'' instance automatically encodes the name and value properties, you should not percent-encode these strings. - Parameters: - name: The name of the query item. For example, in the URL 'http://www.apple.com/search/?q=iPad', the 'name' parameter is 'q'. - value: The value for the query item. For example, in the URL 'http://www.apple.com/search/?q=iPad', the 'value' parameter is 'iPad'. - Returns: A new query item object. * @param name Argument converted to the Objective-C parameter of the same role. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -49,13 +47,11 @@ namespace cocoon static URLQueryItem query_item_with_name(const std::string& name, const std::string& value); /** * @brief Returns the `name` property of `NSURLQueryItem`. - * @details The name of the query item. For example, in the URL 'http://www.apple.com/search/?q=iPad', the 'name' parameter is 'q'. This string is not percent-encoded. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Returns the `value` property of `NSURLQueryItem`. - * @details The value for the query item. For example, in the URL 'http://www.apple.com/search/?q=iPad', the 'value' parameter is 'iPad'. This string is not percent-encoded. * @return The converted Objective-C result. */ std::string value() const; diff --git a/include/generated/url_request.h b/include/generated/url_request.h index f4a980fd..6d7ff585 100644 --- a/include/generated/url_request.h +++ b/include/generated/url_request.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLRequest` (Foundation). - * @details A URL load request that is independent of protocol or URL scheme. Use this type in Swift when you need reference semantics or other Foundation-specific behavior. ''NSURLRequest'' encapsulates two essential properties of a load request: the URL to load and the policies used to load it. In addition, for HTTP and HTTPS requests, ''URLRequest'' includes the HTTP method ('GET', 'POST', and so on) and the HTTP headers. Finally, custom protocols can support custom properties as explained in \. ''NSURLRequest'' only represents information about the request. Use other classes, such as ''URLSession'', to send the request to a server. See \ and \ for an introduction to these techniques. The mutable subclass of ''NSURLRequest'' is ''NSMutableURLRequest''. > Important: > The Swift overlay to the Foundation framework provides the ''URLRequest'' structure, which bridges to the ''NSURLRequest'' class and its mutable subclass, ''NSMutableURLRequest''. For more information about value types, see \. \#\#\# Reserved HTTP headers The URL Loading System handles various aspects of the HTTP protocol for you (HTTP 1.1 persistent connections, proxies, authentication, and so on). As part of this support, the URL Loading System takes responsibility for certain HTTP headers: - 'Content-Length' - 'Authorization' - 'Connection' - 'Host' - 'Proxy-Authenticate' - 'Proxy-Authorization' - 'WWW-Authenticate' If you set a value for one of these reserved headers, the system may ignore the value you set, or overwrite it with its own value, or simply not send it. Moreover, the exact behavior may change over time. To avoid confusing problems like this, do not set these headers directly. The URL Loading System sets the 'Content-Length' header based on whether the request body has a known length: - If so, it uses the identity transfer encoding and sets the 'Content-Length' header to that known length. You see this when you set the request body to a data object. - If not, it uses the chunked transfer encoding and omits the 'Content-Length' header. You see this when you set the request body to a stream. \#\#\# Custom protocol properties If you implement a custom URL protocol by subclassing ''URLProtocol'', and it needs protocol-specific properties, extend ''NSURLRequest'' with accessor methods for those custom properties. In your accessor methods, call ''URLProtocol/property(forKey:in:)'' and ''URLProtocol/setProperty(:forKey:in:)'' to associate property values with the request. + * @details \@class NSURLRequest \@abstract An NSURLRequest object represents a URL load request in a manner independent of protocol and URL scheme. \@discussion NSURLRequest encapsulates two basic data elements about a URL load request: \

    \
  • The URL to load. \
  • The policy to use when consulting the URL content cache made available by the implementation. \
In addition, NSURLRequest is designed to be extended to support protocol-specific data by adding categories to access a property object provided in an interface targeted at protocol implementors. \
    \
  • Protocol implementors should direct their attention to the NSURLRequestExtensibility category on NSURLRequest for more information on how to provide extensions on NSURLRequest to support protocol-specific request information. \
  • Clients of this API who wish to create NSURLRequest objects to load URL content should consult the protocol-specific NSURLRequest categories that are available. The NSHTTPURLRequest category on NSURLRequest is an example. \
\

Objects of this class are used to create NSURLConnection instances, which can are used to perform the load of a URL, or as input to the NSURLConnection class method which performs synchronous loads. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,14 +48,14 @@ namespace cocoon explicit URLRequest(Adopt adopt); /** * @brief Calls `+[NSURLRequest requestWithURL:]`. - * @details Allocates and initializes an 'NSURLRequest' with the given URL. Default values are used for cache policy ('NSURLRequestUseProtocolCachePolicy') and timeout interval (60 seconds). - Parameter URL: The URL for the request. - Returns: A newly-created and autoreleased 'NSURLRequest' instance. + * @details \@method requestWithURL: \@abstract Allocates and initializes an NSURLRequest with the given URL. \@discussion Default values are used for cache policy (NSURLRequestUseProtocolCachePolicy) and timeout interval (60 seconds). \@param URL The URL for the request. \@result A newly-created and autoreleased NSURLRequest instance. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URLRequest request_with_url(const URL& url); /** * @brief Calls `+[NSURLRequest requestWithURL:cachePolicy:timeoutInterval:]`. - * @details Allocates and initializes an 'NSURLRequest' with the given URL and cache policy. - Parameters: - URL: The URL for the request. - cachePolicy: The cache policy for the request. - timeoutInterval: The timeout interval for the request, in seconds. - Returns: A newly-created and autoreleased 'NSURLRequest' instance. + * @details \@method requestWithURL:cachePolicy:timeoutInterval: \@abstract Allocates and initializes a NSURLRequest with the given URL and cache policy. \@param URL The URL for the request. \@param cachePolicy The cache policy for the request. \@param timeoutInterval The timeout interval for the request. See the commentary for the \timeoutInterval\ for more information on timeout intervals. \@result A newly-created and autoreleased NSURLRequest instance. * @param url Argument converted to the Objective-C parameter of the same role. * @param cache_policy Argument converted to the Objective-C parameter of the same role. * @param timeout_interval Argument converted to the Objective-C parameter of the same role. @@ -64,92 +64,92 @@ namespace cocoon static URLRequest request_with_url(const URL& url, URLRequestCachePolicy cache_policy, double timeout_interval); /** * @brief Calls `-[NSURLRequest valueForHTTPHeaderField:]`. - * @details Returns the value which corresponds to the given header field. In keeping with the HTTP RFC, HTTP header field names are case-insensitive. - Parameter field: The header field name to use for the lookup (case-insensitive). - Returns: The value associated with the given header field, or 'nil' if there is no value associated with the given header field. + * @details \@method valueForHTTPHeaderField: \@abstract Returns the value which corresponds to the given header field. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive. \@param field the header field name to use for the lookup (case-insensitive). \@result the value associated with the given header field, or nil if there is no value associated with the given header field. * @param field Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string value_for_http_header_field(const std::string& field) const; /** * @brief Returns the `HTTPBody` property of `NSURLRequest`. - * @details The request body data of the receiver. This data is sent as the message body of the request, as in done in an HTTP POST request. + * @details \@abstract Returns the request body data of the receiver. \@discussion This data is sent as the message body of the request, as in done in an HTTP POST request. \@result The request body data of the receiver. * @return The converted Objective-C result. */ std::vector http_body() const; /** * @brief Returns the `HTTPBodyStream` property of `NSURLRequest`. - * @details The request body stream of the receiver, if any. The stream is returned for examination only; it is not safe for the caller to manipulate the stream in any way. Note that the 'HTTPBodyStream' and 'HTTPBody' are mutually exclusive - only one can be set on a given request. Also note that the body stream is preserved across copies, but is lost when the request is coded via the 'NSCoding' protocol. + * @details \@abstract Returns the request body stream of the receiver if any has been set \@discussion The stream is returned for examination only; it is not safe for the caller to manipulate the stream in any way. Also note that the HTTPBodyStream and HTTPBody are mutually exclusive - only one can be set on a given request. Also note that the body stream is preserved across copies, but is LOST when the request is coded via the NSCoding protocol \@result The request body stream of the receiver. * @return The converted Objective-C result. */ InputStream http_body_stream() const; /** * @brief Returns the `HTTPMethod` property of `NSURLRequest`. - * @details The HTTP request method of the receiver. + * @details \@abstract Returns the HTTP request method of the receiver. \@result the HTTP request method of the receiver. * @return The converted Objective-C result. */ std::string http_method() const; /** * @brief Returns the `HTTPShouldHandleCookies` property of `NSURLRequest`. - * @details A Boolean value that indicates whether the default cookie handling will happen for this request. + * @details \@abstract Determine whether default cookie handling will happen for this request. \@discussion NOTE: This value is not used prior to 10.3 \@result YES if cookies will be sent with and set for this request; otherwise NO. * @return The converted Objective-C result. */ bool http_should_handle_cookies() const; /** * @brief Returns the `URL` property of `NSURLRequest`. - * @details The URL of the receiver. + * @details \@abstract Returns the URL of the receiver. \@result The URL of the receiver. * @return The converted Objective-C result. */ URL url() const; /** * @brief Returns the `allHTTPHeaderFields` property of `NSURLRequest`. - * @details A dictionary containing all the HTTP header fields of the receiver. + * @details \@abstract Returns a dictionary containing all the HTTP header fields of the receiver. \@result a dictionary containing all the HTTP header fields of the receiver. * @return The converted Objective-C result. */ std::map all_http_header_fields() const; /** * @brief Returns the `allowsCellularAccess` property of `NSURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use the built-in cellular radios (if present). + * @details \@abstract returns whether a connection created with this request is allowed to use the built in cellular radios (if present). \@result YES if the receiver is allowed to use the built in cellular radios to satisfy the request, NO otherwise. * @return The converted Objective-C result. */ bool allows_cellular_access() const; /** * @brief Returns the `allowsConstrainedNetworkAccess` property of `NSURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as constrained. + * @details \@abstract returns whether a connection created with this request is allowed to use network interfaces which have been marked as constrained. \@result YES if the receiver is allowed to use an interface marked as constrained to satisfy the request, NO otherwise. * @return The converted Objective-C result. */ bool allows_constrained_network_access() const; /** * @brief Returns the `allowsExpensiveNetworkAccess` property of `NSURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as expensive. + * @details \@abstract returns whether a connection created with this request is allowed to use network interfaces which have been marked as expensive. \@result YES if the receiver is allowed to use an interface marked as expensive to satisfy the request, NO otherwise. * @return The converted Objective-C result. */ bool allows_expensive_network_access() const; /** * @brief Returns the `allowsPersistentDNS` property of `NSURLRequest`. - * @details A Boolean value that indicates whether storing and usage of DNS answers in a persistent per-process cache is allowed. This should only be set for hostnames whose resolutions are not expected to change across networks. Defaults to 'NO'. + * @details \@abstract Allows storing and usage of DNS answers, potentially beyond TTL expiry, in a persistent per-process cache. This should only be set for hostnames whose resolutions are not expected to change across networks. \@discussion YES, if the DNS lookup for this request is allowed to use a persistent per-process cache, NO otherwise. Defaults to NO. * @return The converted Objective-C result. */ bool allows_persistent_dns() const; /** * @brief Returns the `allowsUltraConstrainedNetworkAccess` property of `NSURLRequest`. - * @details A Boolean value that indicates whether a connection created with this request is allowed to use network interfaces which have been marked as ultra constrained. + * @details \@abstract returns whether a connection created with this request is allowed to use network interfaces which have been marked as ultra constrained. \@result YES if the receiver is allowed to use an interface marked as ultra constrained to satisfy the request, NO otherwise. * @return The converted Objective-C result. */ bool allows_ultra_constrained_network_access() const; /** * @brief Returns the `assumesHTTP3Capable` property of `NSURLRequest`. - * @details A Boolean value that indicates whether the server is assumed to support HTTP/3. When 'YES', enables QUIC racing without HTTP/3 service discovery. Defaults to 'NO'. The default may be 'YES' in a future OS update. + * @details \@abstract returns whether we assume that server supports HTTP/3. Enables QUIC racing without HTTP/3 service discovery. \@result YES if server endpoint is known to support HTTP/3. Defaults to NO. The default may be YES in a future OS update. * @return The converted Objective-C result. */ bool assumes_http3_capable() const; /** * @brief Returns the `attribution` property of `NSURLRequest`. - * @details The 'NSURLRequestAttribution' associated with this request. Returns 'NSURLRequestAttributionDeveloper' for requests that have not explicitly set an attribution. + * @details \@abstract Returns the NSURLRequestAttribution associated with this request. \@discussion This will return NSURLRequestAttributionDeveloper for requests that have not explicitly set an attribution. \@result The NSURLRequestAttribution associated with this request. * @return The converted Objective-C result. */ URLRequestAttribution attribution() const; /** * @brief Returns the `cachePolicy` property of `NSURLRequest`. - * @details The cache policy of the receiver. + * @details \@abstract Returns the cache policy of the receiver. \@result The cache policy of the receiver. * @return The converted Objective-C result. */ URLRequestCachePolicy cache_policy() const; @@ -161,31 +161,31 @@ namespace cocoon std::string cookie_partition_identifier() const; /** * @brief Returns the `mainDocumentURL` property of `NSURLRequest`. - * @details The main document URL associated with this load. This URL is used for the cookie "same domain as main document" policy, and attributing the request as a sub-resource of a user-specified URL. There may also be other future uses. + * @details \@abstract The main document URL associated with this load. \@discussion This URL is used for the cookie "same domain as main document" policy, and attributing the request as a sub-resource of a user-specified URL. There may also be other future uses. See setMainDocumentURL: \@result The main document URL. * @return The converted Objective-C result. */ URL main_document_url() const; /** * @brief Returns the `networkServiceType` property of `NSURLRequest`. - * @details The 'NSURLRequestNetworkServiceType' associated with this request. Returns 'NSURLNetworkServiceTypeDefault' for requests that have not explicitly set a network service type. + * @details \@abstract Returns the NSURLRequestNetworkServiceType associated with this request. \@discussion This will return NSURLNetworkServiceTypeDefault for requests that have not explicitly set a networkServiceType (using the setNetworkServiceType method). \@result The NSURLRequestNetworkServiceType associated with this request. * @return The converted Objective-C result. */ URLRequestNetworkServiceType network_service_type() const; /** * @brief Returns the `requiresDNSSECValidation` property of `NSURLRequest`. - * @details A Boolean value that indicates whether a request requires DNSSEC validation during DNS lookup. 'YES' if the DNS lookup for this request should require DNSSEC validation. Defaults to 'NO'. + * @details \@abstract sets whether a request is required to do DNSSEC validation during DNS lookup. \@discussion YES, if the DNS lookup for this request should require DNSSEC validation, No otherwise. Defaults to NO. * @return The converted Objective-C result. */ bool requires_dnssec_validation() const; /** * @brief Returns the `supportsSecureCoding` property of `NSURLRequest`. - * @details Indicates that 'NSURLRequest' implements the 'NSSecureCoding' protocol. + * @details \@property supportsSecureCoding \@abstract Indicates that NSURLRequest implements the NSSecureCoding protocol. \@result A BOOL value set to YES. * @return The converted Objective-C result. */ static bool supports_secure_coding(); /** * @brief Returns the `timeoutInterval` property of `NSURLRequest`. - * @details The timeout interval of the receiver, measured in seconds. The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The "idle interval" is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. + * @details \@abstract Returns the timeout interval of the receiver. \@discussion The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The "idle interval" is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. This timeout interval is measured in seconds. \@result The timeout interval of the receiver. * @return The converted Objective-C result. */ double timeout_interval() const; diff --git a/include/generated/url_response.h b/include/generated/url_response.h index fccf23cd..917c1532 100644 --- a/include/generated/url_response.h +++ b/include/generated/url_response.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLResponse` (Foundation). - * @details The metadata associated with the response to a URL load request, independent of protocol and URL scheme. The related ''HTTPURLResponse'' class is a commonly used subclass of ''URLResponse'' whose objects represent a response to an HTTP URL load request and store additional protocol-specific information such as the response headers. Whenever you make an HTTP request, the ''URLResponse'' object you get back is actually an instance of the ''HTTPURLResponse'' class. > Note: > ''URLResponse'' objects don't contain the actual bytes representing the content of a URL. Instead, the data is returned either a piece at a time through delegate calls or in its entirety when the request completes, depending on the method and class used to initiate the request. > > Read \ to learn various ways to receive the content data from a URL load. + * @details \@class NSURLResponse \@abstract An NSURLResponse object represents a URL load response in a manner independent of protocol and URL scheme. \@discussion NSURLResponse encapsulates the metadata associated with a URL load. Note that NSURLResponse objects do not contain the actual bytes representing the content of a URL. See NSURLConnection and NSURLConnectionDelegate for more information about receiving the content data for a URL load. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -36,31 +36,31 @@ namespace cocoon explicit URLResponse(Adopt adopt); /** * @brief Returns the `MIMEType` property of `NSURLResponse`. - * @details The MIME type of the response. The MIME type is often provided by the response's originating source. However, that value may be changed or corrected by a protocol implementation if it can be determined that the response's source reported the information incorrectly. If the response's originating source does not provide a MIME type, an attempt to guess the MIME type may be made. + * @details \@abstract Returns the MIME type of the receiver. \@discussion The MIME type is based on the information provided from an origin source. However, that value may be changed or corrected by a protocol implementation if it can be determined that the origin server or source reported the information incorrectly or imprecisely. An attempt to guess the MIME type may be made if the origin source did not report any such information. \@result The MIME type of the receiver. * @return The converted Objective-C result. */ std::string mime_type() const; /** * @brief Returns the `URL` property of `NSURLResponse`. - * @details The URL for the response. + * @details \@abstract Returns the URL of the receiver. \@result The URL of the receiver. * @return The converted Objective-C result. */ URL url() const; /** * @brief Returns the `expectedContentLength` property of `NSURLResponse`. - * @details The expected length of the response's content. This property's value is 'NSURLResponseUnknownLength' if the length can't be determined. Some protocol implementations report the content length as part of the response, but not all protocols guarantee to deliver that amount of data. Your app should be prepared to deal with more or less data. + * @details \@abstract Returns the expected content length of the receiver. \@discussion Some protocol implementations report a content length as part of delivering load metadata, but not all protocols guarantee the amount of data that will be delivered in actuality. Hence, this method returns an expected amount. Clients should use this value as an advisory, and should be prepared to deal with either more or less data. \@result The expected content length of the receiver, or -1 if there is no expectation that can be arrived at regarding expected content length. * @return The converted Objective-C result. */ std::int64_t expected_content_length() const; /** * @brief Returns the `suggestedFilename` property of `NSURLResponse`. - * @details A suggested filename for the response data. Accessing this property attempts to generate a filename using the following information, in order: 1. A filename specified using the content disposition header. 2. The last path component of the URL. 3. The host of the URL. If the host of URL can't be converted to a valid filename, the filename '"unknown"' is used. In most cases, this property appends the proper file extension based on the MIME type. Accessing this property always returns a valid filename regardless of whether the resource is saved to disk. + * @details \@abstract Returns a suggested filename if the resource were saved to disk. \@discussion The method first checks if the server has specified a filename using the content disposition header. If no valid filename is specified using that mechanism, this method checks the last path component of the URL. If no valid filename can be obtained using the last path component, this method uses the URL's host as the filename. If the URL's host can't be converted to a valid filename, the filename "unknown" is used. In most cases, this method appends the proper file extension based on the MIME type. This method always returns a valid filename. \@result A suggested filename to use if saving the resource to disk. * @return The converted Objective-C result. */ std::string suggested_filename() const; /** * @brief Returns the `textEncodingName` property of `NSURLResponse`. - * @details The name of the text encoding provided by the response's originating source. If no text encoding was provided by the protocol, this property's value is 'nil'. You can convert this string to a 'CFStringEncoding' value by calling 'CFStringConvertIANACharSetNameToEncoding(:)'. You can subsequently convert that value to an 'NSStringEncoding' value by calling 'CFStringConvertEncodingToNSStringEncoding(:)'. + * @details \@abstract Returns the name of the text encoding of the receiver. \@discussion This name will be the actual string reported by the origin source during the course of performing a protocol-specific URL load. Clients can inspect this string and convert it to an NSStringEncoding or CFStringEncoding using the methods and functions made available in the appropriate framework. \@result The name of the text encoding of the receiver, or nil if no text encoding was specified. * @return The converted Objective-C result. */ std::string text_encoding_name() const; diff --git a/include/generated/url_session.h b/include/generated/url_session.h index ba69c597..de2e9c04 100644 --- a/include/generated/url_session.h +++ b/include/generated/url_session.h @@ -24,7 +24,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLSession` (Foundation). - * @details An object that coordinates a group of related, network data transfer tasks. The ''URLSession'' class and related classes provide an API for downloading data from and uploading data to endpoints indicated by URLs. Your app can also use this API to perform background downloads when your app isn't running or, in iOS, while your app is suspended. You can use the related ''URLSessionDelegate'' and ''URLSessionTaskDelegate'' to support authentication and receive events like redirection and task completion. > Note: > The ''URLSession'' API involves many different classes that work together in a fairly complex way which may not be obvious if you read the reference documentation by itself. Before using the API, read the overview in the \ topic. The articles in the Essentials, Uploading, and Downloading sections offer examples of performing common tasks with ''URLSession''. Your app creates one or more ''URLSession'' instances, each of which coordinates a group of related data-transfer tasks. For example, if you're creating a web browser, your app might create one session per tab or window, or one session for interactive use and another for background downloads. Within each session, your app adds a series of tasks, each of which represents a request for a specific URL (following HTTP redirects, if necessary). \#\#\# Types of URL sessions The tasks within a given URL session share a common session configuration object, which defines connection behavior, like the maximum number of simultaneous connections to make to a single host, whether connections can use the cellular network, and so on. ''URLSession'' has a singleton ''shared'' session (which doesn't have a configuration object) for basic requests. It's not as customizable as sessions you create, but it serves as a good starting point if you have very limited requirements. You access this session by calling the shared class method. For other kinds of sessions, you create a ''URLSession'' with one of three kinds of configurations: - A default session behaves much like the shared session, but lets you configure it. You can also assign a delegate to the default session to obtain data incrementally. - Ephemeral sessions are similar to shared sessions, but don't write caches, cookies, or credentials to disk. - Background sessions let you perform uploads and downloads of content in the background while your app isn't running. See Creating a session configuration object in the ''URLSessionConfiguration'' class for details on creating each type of configuration. \#\#\# Types of URL session tasks Within a session, you create tasks that optionally upload data to a server and then retrieve data from the server either as a file on disk or as one or more ''NSData'' objects in memory. The ''URLSession'' API provides four types of tasks: - Data tasks send and receive data using ''NSData'' objects. Data tasks are intended for short, often interactive requests to a server. - Upload tasks are similar to data tasks, but they also send data (often in the form of a file), and support background uploads while the app isn't running. - Download tasks retrieve data in the form of a file, and support background downloads and uploads while the app isn't running. - WebSocket tasks exchange messages over TCP and TLS, using the WebSocket protocol defined in [RFC 6455](https://tools.ietf.org/html/rfc6455). \#\#\# Using a session delegate Tasks in a session also share a common delegate object. You implement this delegate to provide and obtain information when various events occur, including when: - Authentication fails. - Data arrives from the server. - Data becomes available for caching. If you don't need the features provided by a delegate, you can use this API without providing one by passing 'nil' when you create a session. > Important: > The session object keeps a strong reference to the delegate until your app exits or explicitly invalidates the session. If you don't invalidate the session, your app leaks memory until the app terminates. Each task you create with the session calls back to the session's delegate, using the methods defined in ''URLSessionTaskDelegate''. You can also intercept these callbacks before they reach the session delegate by populating a separate ''URLSessionTask/delegate'' that's specific to the task. \#\#\# Asynchronicity and URL sessions Like most networking APIs, the ''URLSession'' API is highly asynchronous. It returns data to your app in one of three ways, depending on the methods you call: - If you're using Swift, you can use the methods marked with the 'async' keyword to perform common tasks. For example, ''data(from:delegate:)'' fetches data, while ''download(from:delegate:)'' downloads files. Your call point uses the 'await' keyword to suspend running until the transfer completes. You can also use the ''bytes(from:delegate:)'' method to receive data as an \. With this approach, you use the 'for'-'await'-'in' syntax to iterate over the data as your app receives it. The ''URL'' type also offers covenience methods to fetch bytes or lines from the shared URL session. - In Swift or Objective-C, you can provide a completion handler block, which runs when the transfer completes. - In Swift or Objective-C, you can receive callbacks to a delegate method as the transfer progresses and immediately after it completes. In addition to delivering this information to delegates, the ''URLSession'' provides status and progress properties. Query these properties if you need to make programmatic decisions based on the current state of the task (with the caveat that its state can change at any time). \#\#\# Protocol support The ''URLSession'' class natively supports the 'data', 'file', 'ftp', 'http', and 'https' URL schemes, with transparent support for proxy servers and SOCKS gateways, as configured in the user's system preferences. ''URLSession'' supports the HTTP/1.1, HTTP/2, and HTTP/3 protocols. HTTP/2 support, as described by [RFC 7540](https://tools.ietf.org/html/rfc7540), requires a server that supports Application-Layer Protocol Negotiation (ALPN). You can also add support for your own custom networking protocols and URL schemes (for your app's private use) by subclassing ''URLProtocol''. \#\#\# App Transport Security (ATS) iOS 9.0 and macOS 10.11 and later use App Transport Security (ATS) for all HTTP connections made with ''URLSession''. ATS requires that HTTP connections use HTTPS ([RFC 2818](https://tools.ietf.org/html/rfc2818)). For more information, see \. \#\#\# Foundation copying behavior Session and task objects conform to the ''NSCopying'' protocol as follows: - When your app copies a session or task object, you get the same object back. - When your app copies a configuration object, you get a new copy you can independently modify. \#\#\# Thread safety The URL session API is thread-safe. You can freely create sessions and tasks in any thread context. When your delegate methods call the provided completion handlers, the work is automatically scheduled on the correct delegate queue. + * @details FOUNDATION_EXPORT const int64_t NSURLSessionTransferSizeUnknown API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)); / -1LL * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -59,14 +59,14 @@ namespace cocoon explicit URLSession(Adopt adopt); /** * @brief Calls `-[NSURLSession dataTaskWithRequest:]`. - * @details Creates a task that retrieves the contents of a URL based on the specified URL request object. By creating a task based on a request object, you can tune various aspects of the task's behavior, including the cache policy and timeout interval. After you create the task, you must start it by calling its '-resume' method. - Parameter request: A URL request object that provides request-specific information such as the URL, cache policy, request type, and body data or body stream. - Returns: The new session data task. + * @details Creates a data task with the given request. The request may have a body stream. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionDataTask data_task_with_request(const URLRequest& request) const; /** * @brief Calls `-[NSURLSession dataTaskWithRequest:completionHandler:]`. - * @details Creates a task that retrieves the contents of a URL based on the specified URL request object, and calls a handler upon completion. By creating a task based on a request object, you can tune various aspects of the task's behavior, including the cache policy and timeout interval. By using the completion handler, the task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting 'NSData', 'NSURLResponse', and 'NSError' objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called. After you create the task, you must start it by calling its '-resume' method. - Parameter request: A URL request object that provides the URL, cache policy, request type, body data or body stream, and so on. - Parameter completionHandler: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. + * @details data task convenience methods. These methods create tasks that bypass the normal delegate calls for response and data delivery, and provide a simple cancelable asynchronous interface to receiving data. Errors will be returned in the NSURLErrorDomain, see \. The delegate, if any, will still be called for authentication challenges. * @param request Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -74,14 +74,13 @@ namespace cocoon URLSessionDataTask data_task_with_request(const URLRequest& request, std::function, URLResponse, Error)> completion_handler) const; /** * @brief Calls `-[NSURLSession dataTaskWithURL:]`. - * @details Creates a task that retrieves the contents of the specified URL. After you create the task, you must start it by calling its '-resume' method. The task calls methods on the session's delegate to provide you with the response metadata, response data, and so on. - Parameter url: The URL to be retrieved. - Returns: The new session data task. + * @details Creates a data task to retrieve the contents of the given URL. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionDataTask data_task_with_url(const URL& url) const; /** * @brief Calls `-[NSURLSession dataTaskWithURL:completionHandler:]`. - * @details Creates a task that retrieves the contents of the specified URL, then calls a handler upon completion. After you create the task, you must start it by calling its '-resume' method. By using the completion handler, the task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting 'NSData', 'NSURLResponse', and 'NSError' objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called. - Parameter url: The URL to be retrieved. - Parameter completionHandler: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. * @param url Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -89,14 +88,14 @@ namespace cocoon URLSessionDataTask data_task_with_url(const URL& url, std::function, URLResponse, Error)> completion_handler) const; /** * @brief Calls `-[NSURLSession downloadTaskWithRequest:]`. - * @details Creates a download task that retrieves the contents of a URL based on the specified URL request object and saves the results to a file. By creating a task based on a request object, you can tune various aspects of the task's behavior, including the cache policy and timeout interval. After you create the task, you must start it by calling its '-resume' method. The task calls methods on the session's delegate to provide you with progress notifications, the location of the resulting temporary file, and so on. - Parameter request: A URL request object that provides the URL, cache policy, request type, body data or body stream, and so on. - Returns: The new session download task. + * @details Creates a download task with the given request. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionDownloadTask download_task_with_request(const URLRequest& request) const; /** * @brief Calls `-[NSURLSession downloadTaskWithRequest:completionHandler:]`. - * @details Creates a download task that retrieves the contents of a URL based on the specified URL request object, saves the results to a file, and calls a handler upon completion. By creating a task based on a request object, you can tune various aspects of the task's behavior, including the cache policy and timeout interval. After you create the task, you must start it by calling its '-resume' method. - Parameter request: A URL request object that provides the URL, cache policy, request type, body data or body stream, and so on. - Parameter completionHandler: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. + * @details download task convenience methods. When a download successfully completes, the NSURL will point to a file that must be read or copied during the invocation of the completion routine. The file will be removed automatically. * @param request Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -104,14 +103,13 @@ namespace cocoon URLSessionDownloadTask download_task_with_request(const URLRequest& request, std::function completion_handler) const; /** * @brief Calls `-[NSURLSession downloadTaskWithResumeData:]`. - * @details Creates a download task to resume a previously canceled or failed download. After you create the task, you must start it by calling its '-resume' method. This method is equivalent to '-downloadTaskWithResumeData:completionHandler:' with a 'nil' completion handler. For detailed usage information, including ways to obtain a resume data object, see that method. - Parameter resumeData: A data object that provides the data necessary to resume a download. - Returns: The new session download task. + * @details Creates a download task with the resume data. If the download cannot be successfully resumed, URLSession:task:didCompleteWithError: will be called. * @param resume_data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionDownloadTask download_task_with_resume_data(const std::vector& resume_data) const; /** * @brief Calls `-[NSURLSession downloadTaskWithResumeData:completionHandler:]`. - * @details Creates a download task to resume a previously canceled or failed download and calls a handler upon completion. Your app can obtain a 'resumeData' object in two ways: - If your app cancels an existing transfer by calling '-cancelByProducingResumeData:', the session object passes a 'resumeData' object to the completion handler that you provided in that call. - If a transfer fails, the session object provides an 'NSError' object either to its delegate or to the task's completion handler. In that object, the 'NSURLSessionDownloadTaskResumeData' key in the 'userInfo' dictionary contains a 'resumeData' object. After you create the task, you must start it by calling its '-resume' method. > Note: A download can be resumed only if it is an HTTP or HTTPS 'GET' request, and only > if the remote server supports byte-range requests (with the 'Range' header) and provides > the 'ETag' or 'Last-Modified' header in its responses. - Parameter resumeData: A data object that provides the data necessary to resume the download. - Parameter completionHandler: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. * @param resume_data Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -119,14 +117,13 @@ namespace cocoon URLSessionDownloadTask download_task_with_resume_data(const std::vector& resume_data, std::function completion_handler) const; /** * @brief Calls `-[NSURLSession downloadTaskWithURL:]`. - * @details Creates a download task that retrieves the contents of the specified URL and saves the results to a file. After you create the task, you must start it by calling its '-resume' method. - Parameter url: The URL to download. - Returns: The new session download task. + * @details Creates a download task to download the contents of the given URL. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionDownloadTask download_task_with_url(const URL& url) const; /** * @brief Calls `-[NSURLSession downloadTaskWithURL:completionHandler:]`. - * @details Creates a download task that retrieves the contents of the specified URL, saves the results to a file, and calls a handler upon completion. After you create the task, you must start it by calling its '-resume' method. - Parameter url: The URL to download. - Parameter completionHandler: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. * @param url Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -134,48 +131,46 @@ namespace cocoon URLSessionDownloadTask download_task_with_url(const URL& url, std::function completion_handler) const; /** * @brief Calls `-[NSURLSession finishTasksAndInvalidate]`. - * @details Invalidates the session, allowing any outstanding tasks to finish. This method returns immediately without waiting for tasks to finish. Once a session is invalidated, new tasks cannot be created in the session, but existing tasks continue until completion. After the last task finishes and the session makes the last delegate call related to those tasks, the session calls the 'URLSession:didBecomeInvalidWithError:' method on its delegate, then breaks references to the delegate and callback objects. After invalidation, session objects cannot be reused. To cancel all outstanding tasks, call '-invalidateAndCancel' instead. > Important: Calling this method on the shared session has no effect. When invalidating a background session, it is not safe to create another background session with the same identifier until 'URLSession:didBecomeInvalidWithError:' has been issued. + * @details -finishTasksAndInvalidate returns immediately and existing tasks will be allowed to run to completion. New tasks may not be created. The session will continue to make delegate callbacks until URLSession:didBecomeInvalidWithError: has been issued. -finishTasksAndInvalidate and -invalidateAndCancel do not have any effect on the shared session instance. When invalidating a background session, it is not safe to create another background session with the same identifier until URLSession:didBecomeInvalidWithError: has been issued. */ void finish_tasks_and_invalidate() const; /** * @brief Calls `-[NSURLSession flushWithCompletionHandler:]`. - * @details Flushes cookies and credentials to disk, clears transient caches, and ensures that future requests occur on a new TCP connection. - Parameter completionHandler: The completion handler to call when the flush operation is complete. This handler is executed on the delegate queue. + * @details - (void)resetWithCompletionHandler:(void (NS_SWIFT_SENDABLE ^)(void))completionHandler; / empty all cookies, cache and credential stores, removes disk files, issues -flushWithCompletionHandler:. Invokes completionHandler() on the delegate queue. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void flush_with_completion_handler(std::function completion_handler) const; /** * @brief Calls `-[NSURLSession getAllTasksWithCompletionHandler:]`. - * @details Asynchronously calls a completion callback with all tasks in a session. - Parameter completionHandler: The completion handler to call with the list of tasks. + * @details - (void)getTasksWithCompletionHandler:(void (NS_SWIFT_SENDABLE ^)(NSArray\ dataTasks, NSArray\ uploadTasks, NSArray\ downloadTasks))completionHandler NS_SWIFT_ASYNC_NAME(getter:tasks()); / invokes completionHandler with outstanding data, upload and download tasks. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void get_all_tasks_with_completion_handler(std::function)> completion_handler) const; /** * @brief Calls `-[NSURLSession getTasksWithCompletionHandler:]`. - * @details Asynchronously calls a completion callback with all data, upload, and download tasks in a session. - Parameter completionHandler: The completion handler to call with the list of tasks. This handler is executed on the delegate queue. The arrays passed to the completion handler contain any tasks that you have created within the session, not including any tasks that have been invalidated after completing, failing, or being cancelled. + * @details - (void)flushWithCompletionHandler:(void (NS_SWIFT_SENDABLE ^)(void))completionHandler; / flush storage to disk and clear transient network caches. Invokes completionHandler() on the delegate queue. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void get_tasks_with_completion_handler(std::function, std::vector, std::vector)> completion_handler) const; /** * @brief Calls `-[NSURLSession invalidateAndCancel]`. - * @details Cancels all outstanding tasks and then invalidates the session. Once invalidated, references to the delegate and callback objects are broken. After invalidation, session objects cannot be reused. To allow outstanding tasks to run until completion, call '-finishTasksAndInvalidate' instead. > Important: Calling this method on the shared session has no effect. + * @details -invalidateAndCancel acts as -finishTasksAndInvalidate, but issues -cancel to all outstanding tasks for this session. Note task cancellation is subject to the state of the task, and some tasks may have already have completed at the time they are sent -cancel. */ void invalidate_and_cancel() const; /** * @brief Calls `-[NSURLSession resetWithCompletionHandler:]`. - * @details Empties all cookies, caches and credential stores, removes disk files, flushes in-progress downloads to disk, and ensures that future requests occur on a new socket. - Parameter completionHandler: The completion handler to call when the reset operation is complete. This handler is executed on the delegate queue. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void reset_with_completion_handler(std::function completion_handler) const; /** * @brief Calls `+[NSURLSession sessionWithConfiguration:]`. - * @details Creates a session with the specified session configuration. - Parameter configuration: A configuration object that specifies certain behaviors, such as caching policies, timeouts, proxies, pipelining, TLS versions to support, cookie policies, credential storage, and so on. See 'NSURLSessionConfiguration' for more information. Calling this method is equivalent to calling '+sessionWithConfiguration:delegate:delegateQueue:' with a 'nil' delegate and queue. + * @details Customization of NSURLSession occurs during creation of a new session. If you only need to use the convenience routines with custom configuration options it is not necessary to specify a delegate. If you do specify a delegate, the delegate will be retained until after the delegate has been sent the URLSession:didBecomeInvalidWithError: message. * @param configuration Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URLSession session_with_configuration(const URLSessionConfiguration& configuration); /** * @brief Calls `+[NSURLSession sessionWithConfiguration:delegate:delegateQueue:]`. - * @details Creates a session with the specified session configuration, delegate, and operation queue. - Parameter configuration: A configuration object that specifies certain behaviors, such as caching policies, timeouts, proxies, pipelining, TLS versions to support, cookie policies, and credential storage. See 'NSURLSessionConfiguration' for more information. - Parameter delegate: A session delegate object that handles requests for authentication and other session-related events. This delegate object is responsible for handling authentication challenges, for making caching decisions, and for handling other session-related events. If 'nil', the class should be used only with methods that take completion handlers. The session object keeps a strong reference to the delegate until your app exits or explicitly invalidates the session. If you do not invalidate the session by calling '-invalidateAndCancel' or '-finishTasksAndInvalidate', your app leaks memory until it exits. - Parameter queue: An operation queue for scheduling the delegate calls and completion handlers. The queue should be a serial queue, in order to ensure the correct ordering of callbacks. If 'nil', the session creates a serial operation queue for performing all delegate method calls and completion handler calls. * @param configuration Argument converted to the Objective-C parameter of the same role. * @param delegate Argument converted to the Objective-C parameter of the same role. * @param queue Argument converted to the Objective-C parameter of the same role. @@ -184,7 +179,7 @@ namespace cocoon static URLSession session_with_configuration(const URLSessionConfiguration& configuration, const Object& delegate, const OperationQueue& queue); /** * @brief Calls `-[NSURLSession streamTaskWithHostName:port:]`. - * @details Creates a task that establishes a bidirectional TCP/IP connection to a specified hostname and port. After you create the task, you must start it by calling its '-resume' method. - Parameter hostname: The hostname of the connection endpoint. - Parameter port: The port of the connection endpoint. - Returns: The new session stream task. + * @details Creates a bidirectional stream task to a given host and port. * @param hostname Argument converted to the Objective-C parameter of the same role. * @param port Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -192,14 +187,14 @@ namespace cocoon URLSessionStreamTask stream_task_with_host_name(const std::string& hostname, std::int64_t port) const; /** * @brief Calls `-[NSURLSession streamTaskWithNetService:]`. - * @details Creates a task that establishes a bidirectional TCP/IP connection using a specified network service. After you create the task, you must start it by calling its '-resume' method. - Parameter service: An 'NSNetService' object used to determine the endpoint of the TCP/IP connection. This network service is resolved before any data is read or written to the resulting stream task. - Returns: The new session stream task. + * @details Creates a bidirectional stream task with an NSNetService to identify the endpoint. The NSNetService will be resolved before any IO completes. * @param service Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionStreamTask stream_task_with_net_service(const NetService& service) const; /** * @brief Calls `-[NSURLSession uploadTaskWithRequest:fromData:]`. - * @details Creates a task that performs an HTTP request for the specified URL request object and uploads the provided data. An HTTP upload request is any request that contains a request body, such as a 'POST' or 'PUT' request. Upload tasks require you to create a request object so that you can provide metadata for the upload, like HTTP request headers. After you create the task, you must start it by calling its '-resume' method. The task calls methods on the session's delegate to provide you with the upload's progress, response metadata, response data, and so on. - Parameter request: A URL request object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored. - Parameter bodyData: The body data for the request. - Returns: The new session upload task. + * @details Creates an upload task with the given request. The body of the request is provided from the bodyData. * @param request Argument converted to the Objective-C parameter of the same role. * @param body_data Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -207,7 +202,6 @@ namespace cocoon URLSessionUploadTask upload_task_with_request(const URLRequest& request, const std::vector& body_data) const; /** * @brief Calls `-[NSURLSession uploadTaskWithRequest:fromData:completionHandler:]`. - * @details Creates a task that performs an HTTP request for the specified URL request object, uploads the provided data, and calls a handler upon completion. - Parameter request: A URL request object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored. - Parameter bodyData: The body data for the request. - Parameter completionHandler: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. * @param request Argument converted to the Objective-C parameter of the same role. * @param body_data Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. @@ -216,7 +210,7 @@ namespace cocoon URLSessionUploadTask upload_task_with_request(const URLRequest& request, const std::vector& body_data, std::function, URLResponse, Error)> completion_handler) const; /** * @brief Calls `-[NSURLSession uploadTaskWithRequest:fromFile:]`. - * @details Creates a task that performs an HTTP request for uploading the specified file. An HTTP upload request is any request that contains a request body, such as a 'POST' or 'PUT' request. Upload tasks require you to create a request object so that you can provide metadata for the upload, like HTTP request headers. After you create the task, you must start it by calling its '-resume' method. The task calls methods on the session's delegate to provide you with the upload's progress, response metadata, response data, and so on. - Parameter request: A URL request object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored. - Parameter fileURL: The URL of the file to upload. - Returns: The new session upload task. + * @details Creates an upload task with the given request. The body of the request will be created from the file referenced by fileURL * @param request Argument converted to the Objective-C parameter of the same role. * @param file_url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -224,7 +218,7 @@ namespace cocoon URLSessionUploadTask upload_task_with_request(const URLRequest& request, const URL& file_url) const; /** * @brief Calls `-[NSURLSession uploadTaskWithRequest:fromFile:completionHandler:]`. - * @details Creates a task that performs an HTTP request for uploading the specified file, then calls a handler upon completion. - Parameter request: A URL request object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored. - Parameter fileURL: The URL of the file to upload. - Parameter completionHandler: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. + * @details upload convenience method. * @param request Argument converted to the Objective-C parameter of the same role. * @param file_url Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. @@ -248,28 +242,28 @@ namespace cocoon URLSessionUploadTask upload_task_with_resume_data(const std::vector& resume_data, std::function, URLResponse, Error)> completion_handler) const; /** * @brief Calls `-[NSURLSession uploadTaskWithStreamedRequest:]`. - * @details Creates a task that performs an HTTP request for uploading data based on the specified URL request. An HTTP upload request is any request that contains a request body, such as a 'POST' or 'PUT' request. Upload tasks require you to provide a request object so that you can provide metadata for the upload, such as HTTP request headers. After you create the task, you must start it by calling its '-resume' method. The task calls methods on the session's delegate to provide you with the upload's progress, response metadata, response data, and so on. The session's delegate must have a 'URLSession:task:needNewBodyStream:' method that provides the body data to upload. - Parameter request: A URL request object that provides the URL, cache policy, request type, and so on. The body stream and body data in this request object are ignored, and the session calls its delegate's 'URLSession:task:needNewBodyStream:' method to supply an upload body. - Returns: The new session upload task. + * @details Creates an upload task with the given request. The previously set body stream of the request (if any) is ignored and the URLSession:task:needNewBodyStream: delegate will be called when the body payload is required. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionUploadTask upload_task_with_streamed_request(const URLRequest& request) const; /** * @brief Calls `-[NSURLSession webSocketTaskWithRequest:]`. - * @details Creates a WebSocket task for the provided URL request. You can modify the request's properties prior to calling '-resume' on the task. The task uses these properties during the HTTP handshake phase. To add custom protocols, add a header with the key 'Sec-WebSocket-Protocol', and a comma-separated list of protocols you want to negotiate with the server. The custom HTTP headers provided by the client remain unchanged for the handshake with the server. - Parameter request: A URL request that indicates a WebSocket endpoint with which to connect. + * @details Creates a WebSocket task given the request. The request properties can be modified and will be used by the task during the HTTP handshake phase. Clients who want to add custom protocols can do so by directly adding headers with the key Sec-WebSocket-Protocol and a comma separated list of protocols they wish to negotiate with the server. The custom HTTP headers provided by the client will remain unchanged for the handshake with the server. * @param request Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionWebSocketTask web_socket_task_with_request(const URLRequest& request) const; /** * @brief Calls `-[NSURLSession webSocketTaskWithURL:]`. - * @details Creates a WebSocket task for the provided URL. The provided URL must have a 'ws' or 'wss' scheme. - Parameter url: The WebSocket URL with which to connect. + * @details Creates a WebSocket task given the url. The given url must have a ws or wss scheme. * @param url Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URLSessionWebSocketTask web_socket_task_with_url(const URL& url) const; /** * @brief Calls `-[NSURLSession webSocketTaskWithURL:protocols:]`. - * @details Creates a WebSocket task given a URL and an array of protocols. During the WebSocket handshake, the task uses the provided protocols to negotiate a preferred protocol with the server. > Note: The protocol doesn't affect the WebSocket framing. More details on the protocol > are available in RFC 6455, The WebSocket Protocol. - Parameter url: The WebSocket URL with which to connect. - Parameter protocols: An array of protocols to negotiate with the server. + * @details Creates a WebSocket task given the url and an array of protocols. The protocols will be used in the WebSocket handshake to negotiate a preferred protocol with the server Note - The protocol will not affect the WebSocket framing. More details on the protocol can be found by reading the WebSocket RFC * @param url Argument converted to the Objective-C parameter of the same role. * @param protocols Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -277,31 +271,29 @@ namespace cocoon URLSessionWebSocketTask web_socket_task_with_url(const URL& url, const std::vector& protocols) const; /** * @brief Returns the `configuration` property of `NSURLSession`. - * @details A copy of the configuration object for this session. Beginning in iOS 9 and OS X 10.11, 'NSURLSession' objects store a copy of the 'NSURLSessionConfiguration' object passed to their initializers, such that a session's configuration is immutable after initialization. Any further changes to mutable properties on the configuration object passed to a session's initializer or the value returned from a session's configuration property do not affect the behavior of that session. However, you can create a new session with the modified configuration object. * @return The converted Objective-C result. */ URLSessionConfiguration configuration() const; /** * @brief Returns the `delegateQueue` property of `NSURLSession`. - * @details The operation queue provided when this object was created. All delegate method calls and completion handlers related to the session are performed on this queue. The session object keeps a strong reference to this queue until your app exits or the session object is deallocated. If you do not invalidate the session, your app leaks memory until it exits. > Note: This queue must be set at object creation time and may not be changed. * @return The converted Objective-C result. */ OperationQueue delegate_queue() const; /** * @brief Returns the `sessionDescription` property of `NSURLSession`. - * @details An app-defined descriptive label for the session. This property contains a human-readable string that you can use for debugging purposes. This value may be 'nil' and defaults to 'nil'. The value is ignored by the session. + * @details The sessionDescription property is available for the developer to provide a descriptive label for the session. * @return The converted Objective-C result. */ std::string session_description() const; /** * @brief Sets the `sessionDescription` property of `NSURLSession`. - * @details An app-defined descriptive label for the session. This property contains a human-readable string that you can use for debugging purposes. This value may be 'nil' and defaults to 'nil'. The value is ignored by the session. + * @details The sessionDescription property is available for the developer to provide a descriptive label for the session. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_session_description(const std::string& value) const; /** * @brief Returns the `sharedSession` property of `NSURLSession`. - * @details The shared singleton session object. For basic requests, the 'NSURLSession' class provides a shared singleton session object that gives you a reasonable default behavior for creating tasks. Use the shared session to fetch the contents of a URL to memory with just a few lines of code. Unlike the other session types, you don't create the shared session; you merely access it by using this property directly. As a result, you don't provide a delegate or a configuration object. Because the shared session has neither a delegate nor a customizable configuration object, the shared session has important limitations: - You can't obtain data incrementally as it arrives from the server. - You can't significantly customize the default connection behavior. - Your ability to perform authentication is limited. - You can't perform background downloads or uploads when your app isn't running. The shared session uses the shared 'NSURLCache', 'NSHTTPCookieStorage', and 'NSURLCredentialStorage' objects, uses a shared custom networking protocol list (configured with '+[NSURLProtocol registerClass:]' and '+[NSURLProtocol unregisterClass:]'), and is based on a default configuration. + * @details The shared session uses the currently set global NSURLCache, NSHTTPCookieStorage and NSURLCredentialStorage objects. * @return The converted Objective-C result. */ static URLSession shared_session(); diff --git a/include/generated/url_session_configuration.h b/include/generated/url_session_configuration.h index fd228d2d..66c95222 100644 --- a/include/generated/url_session_configuration.h +++ b/include/generated/url_session_configuration.h @@ -14,7 +14,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLSessionConfiguration` (Foundation). - * @details A configuration object that defines behavior and policies for a URL session. An ''URLSessionConfiguration'' object defines the behavior and policies to use when uploading and downloading data using an ''URLSession'' object. When uploading or downloading data, creating a configuration object is always the first step you must take. You use this object to configure the timeout values, caching policies, connection requirements, and other types of information that you intend to use with your ''URLSession'' object. It is important to configure your ''URLSessionConfiguration'' object appropriately before using it to initialize a session object. Session objects make a copy of the configuration settings you provide and use those settings to configure the session. Once configured, the session object ignores any changes you make to the ''URLSessionConfiguration'' object. If you need to modify your transfer policies, you must update the session configuration object and use it to create a new ''URLSession'' object. > Note: > In some cases, the policies defined in this configuration may be overridden by policies specified by an ''NSURLRequest'' object provided for a task. Any policy specified on the request object is respected unless the session's policy is more restrictive. For example, if the session configuration specifies that cellular networking should not be allowed, the ''NSURLRequest'' object cannot request cellular networking. For more information about using configuration objects to create sessions, see ''URLSession''. \#\#\# Types of session configurations The behavior and capabilities of a URL session are largely determined by the kind of configuration used to create the session. The singleton shared session (which has no configuration object) is for basic requests. It's not as customizable as sessions that you create, but it serves as a good starting point if you have very limited requirements. You access this session by calling the shared class method. See that method's discussion for more information about its limitations. Default sessions behave much like the shared session (unless you customize them further), but let you obtain data incrementally using a delegate. You can create a default session configuration by calling the default method on the URLSessionConfiguration class. Ephemeral sessions are similar to default sessions, but they don't write caches, cookies, or credentials to disk. You can create an ephemeral session configuration by calling the ephemeral method on the URLSessionConfiguration class. Background sessions let you perform uploads and downloads of content in the background while your app isn't running. You can create a background session configuration by calling the backgroundSessionConfiguration(\\:) method on the URLSessionConfiguration class. + * @details Configuration options for an NSURLSession. When a session is created, a copy of the configuration object is made - you cannot modify the configuration of a session after it has been created. The shared session uses the global credential, cache and cookie storage objects. An ephemeral session has no persistent disk storage for cookies, cache or credentials. A background session can be used to perform networking operations on behalf of a suspended application, within certain constraints. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -49,176 +49,175 @@ namespace cocoon explicit URLSessionConfiguration(Adopt adopt); /** * @brief Calls `+[NSURLSessionConfiguration backgroundSessionConfigurationWithIdentifier:]`. - * @details Creates a session configuration object that allows HTTP and HTTPS uploads or downloads to be performed in the background. Use this method to initialize a configuration object suitable for transferring data files while the app runs in the background. A session configured with this object hands control of the transfers over to the system, which handles the transfers in a separate process. In iOS, this configuration makes it possible for transfers to continue even when the app itself is suspended or terminated. If an iOS app is terminated by the system and relaunched, the app can use the same 'identifier' to create a new configuration object and session and to retrieve the status of transfers that were in progress at the time of termination. This behavior applies only for normal termination of the app by the system. If the user terminates the app from the multitasking screen, the system cancels all of the session's background transfers. - Parameter identifier: The unique identifier for the configuration object. This parameter must not be 'nil' or an empty string. - Returns: A configuration object that causes the system to perform upload and download tasks in a separate process. * @param identifier Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static URLSessionConfiguration background_session_configuration_with_identifier(const std::string& identifier); /** * @brief Returns the `HTTPAdditionalHeaders` property of `NSURLSessionConfiguration`. - * @details A dictionary of additional headers to send with requests. This property specifies additional headers that are added to all tasks within sessions based on this configuration. If the same header appears in both this dictionary and the request object (where applicable), the request object's value takes precedence. An 'NSURLSession' object is designed to handle various aspects of the HTTP protocol for you. As a result, you should not modify the following headers: 'Authorization', 'Connection', 'Host', 'Proxy-Authenticate', 'Proxy-Authorization', 'WWW-Authenticate'. + * @details Specifies additional headers which will be set on outgoing requests. Note that these headers are added to the request only if not already present. * @return The converted Objective-C result. */ std::vector> http_additional_headers() const; /** * @brief Sets the `HTTPAdditionalHeaders` property of `NSURLSessionConfiguration`. - * @details A dictionary of additional headers to send with requests. This property specifies additional headers that are added to all tasks within sessions based on this configuration. If the same header appears in both this dictionary and the request object (where applicable), the request object's value takes precedence. An 'NSURLSession' object is designed to handle various aspects of the HTTP protocol for you. As a result, you should not modify the following headers: 'Authorization', 'Connection', 'Host', 'Proxy-Authenticate', 'Proxy-Authorization', 'WWW-Authenticate'. + * @details Specifies additional headers which will be set on outgoing requests. Note that these headers are added to the request only if not already present. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_additional_headers(const std::vector>& value) const; /** * @brief Returns the `HTTPCookieAcceptPolicy` property of `NSURLSessionConfiguration`. - * @details A policy constant that determines when cookies should be accepted. This property determines the cookie accept policy for all tasks within sessions based on this configuration. + * @details Policy for accepting cookies. This overrides the policy otherwise specified by the cookie storage. * @return The converted Objective-C result. */ HTTPCookieAcceptPolicy http_cookie_accept_policy() const; /** * @brief Sets the `HTTPCookieAcceptPolicy` property of `NSURLSessionConfiguration`. - * @details A policy constant that determines when cookies should be accepted. This property determines the cookie accept policy for all tasks within sessions based on this configuration. + * @details Policy for accepting cookies. This overrides the policy otherwise specified by the cookie storage. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_cookie_accept_policy(HTTPCookieAcceptPolicy value) const; /** * @brief Returns the `HTTPCookieStorage` property of `NSURLSessionConfiguration`. - * @details The cookie store for storing cookies within this session. To disable cookie storage, set this property to 'nil'. For default and background sessions, the default value is the shared cookie storage object. For ephemeral sessions, the default value is a private cookie storage object that stores data in memory only, and is destroyed when you invalidate the session. + * @details The cookie storage object to use, or nil to indicate that no cookies should be handled * @return The converted Objective-C result. */ HTTPCookieStorage http_cookie_storage() const; /** * @brief Sets the `HTTPCookieStorage` property of `NSURLSessionConfiguration`. - * @details The cookie store for storing cookies within this session. To disable cookie storage, set this property to 'nil'. For default and background sessions, the default value is the shared cookie storage object. For ephemeral sessions, the default value is a private cookie storage object that stores data in memory only, and is destroyed when you invalidate the session. + * @details The cookie storage object to use, or nil to indicate that no cookies should be handled * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_cookie_storage(const HTTPCookieStorage& value) const; /** * @brief Returns the `HTTPMaximumConnectionsPerHost` property of `NSURLSessionConfiguration`. - * @details The maximum number of simultaneous connections to make to a given host. This limit is per session, so if you use multiple sessions, your app as a whole may exceed this limit. The default value is '6'. + * @details The maximum number of simultaneous persistent connections per host * @return The converted Objective-C result. */ std::int64_t http_maximum_connections_per_host() const; /** * @brief Sets the `HTTPMaximumConnectionsPerHost` property of `NSURLSessionConfiguration`. - * @details The maximum number of simultaneous connections to make to a given host. This limit is per session, so if you use multiple sessions, your app as a whole may exceed this limit. The default value is '6'. + * @details The maximum number of simultaneous persistent connections per host * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_maximum_connections_per_host(std::int64_t value) const; /** * @brief Returns the `HTTPShouldSetCookies` property of `NSURLSessionConfiguration`. - * @details A Boolean value that determines whether requests should contain cookies from the cookie store. The default value is 'YES'. + * @details Allow the session to set cookies on requests * @return The converted Objective-C result. */ bool http_should_set_cookies() const; /** * @brief Sets the `HTTPShouldSetCookies` property of `NSURLSessionConfiguration`. - * @details A Boolean value that determines whether requests should contain cookies from the cookie store. The default value is 'YES'. + * @details Allow the session to set cookies on requests * @param value Argument converted to the Objective-C parameter of the same role. */ void set_http_should_set_cookies(bool value) const; /** * @brief Returns the `TLSMaximumSupportedProtocol` property of `NSURLSessionConfiguration`. - * @details The maximum TLS protocol version that the client should request when making connections in this session. + * @details The maximum allowable versions of the TLS protocol, from \ * @return The converted Objective-C result. */ SSLProtocol tls_maximum_supported_protocol() const; /** * @brief Sets the `TLSMaximumSupportedProtocol` property of `NSURLSessionConfiguration`. - * @details The maximum TLS protocol version that the client should request when making connections in this session. + * @details The maximum allowable versions of the TLS protocol, from \ * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tls_maximum_supported_protocol(SSLProtocol value) const; /** * @brief Returns the `TLSMaximumSupportedProtocolVersion` property of `NSURLSessionConfiguration`. - * @details The maximum TLS protocol version that the client should request when making connections in this session. + * @details The maximum allowable versions of the TLS protocol, from \ * @return The converted Objective-C result. */ tls_protocol_version_t tls_maximum_supported_protocol_version() const; /** * @brief Sets the `TLSMaximumSupportedProtocolVersion` property of `NSURLSessionConfiguration`. - * @details The maximum TLS protocol version that the client should request when making connections in this session. + * @details The maximum allowable versions of the TLS protocol, from \ * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tls_maximum_supported_protocol_version(tls_protocol_version_t value) const; /** * @brief Returns the `TLSMinimumSupportedProtocol` property of `NSURLSessionConfiguration`. - * @details The minimum TLS protocol to accept during protocol negotiation. + * @details The minimum allowable versions of the TLS protocol, from \ * @return The converted Objective-C result. */ SSLProtocol tls_minimum_supported_protocol() const; /** * @brief Sets the `TLSMinimumSupportedProtocol` property of `NSURLSessionConfiguration`. - * @details The minimum TLS protocol to accept during protocol negotiation. + * @details The minimum allowable versions of the TLS protocol, from \ * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tls_minimum_supported_protocol(SSLProtocol value) const; /** * @brief Returns the `TLSMinimumSupportedProtocolVersion` property of `NSURLSessionConfiguration`. - * @details The minimum TLS protocol version that the client should accept when making connections in this session. + * @details The minimum allowable versions of the TLS protocol, from \ * @return The converted Objective-C result. */ tls_protocol_version_t tls_minimum_supported_protocol_version() const; /** * @brief Sets the `TLSMinimumSupportedProtocolVersion` property of `NSURLSessionConfiguration`. - * @details The minimum TLS protocol version that the client should accept when making connections in this session. + * @details The minimum allowable versions of the TLS protocol, from \ * @param value Argument converted to the Objective-C parameter of the same role. */ void set_tls_minimum_supported_protocol_version(tls_protocol_version_t value) const; /** * @brief Returns the `URLCache` property of `NSURLSessionConfiguration`. - * @details The URL cache for providing cached responses to requests within the session. To disable caching, set this property to 'nil'. For default sessions, the default value is the shared URL cache object. For background sessions, the default value is 'nil'. For ephemeral sessions, the default value is a private cache object that stores data in memory only, and is destroyed when you invalidate the session. + * @details The URL resource cache, or nil to indicate that no caching is to be performed * @return The converted Objective-C result. */ URLCache url_cache() const; /** * @brief Sets the `URLCache` property of `NSURLSessionConfiguration`. - * @details The URL cache for providing cached responses to requests within the session. To disable caching, set this property to 'nil'. For default sessions, the default value is the shared URL cache object. For background sessions, the default value is 'nil'. For ephemeral sessions, the default value is a private cache object that stores data in memory only, and is destroyed when you invalidate the session. + * @details The URL resource cache, or nil to indicate that no caching is to be performed * @param value Argument converted to the Objective-C parameter of the same role. */ void set_url_cache(const URLCache& value) const; /** * @brief Returns the `URLCredentialStorage` property of `NSURLSessionConfiguration`. - * @details A credential store that provides credentials for authentication. To not use a credential store, set this property to 'nil'. For default and background sessions, the default value is the shared credential storage object. For ephemeral sessions, the default value is a private credential store object that stores data in memory only, and is destroyed when you invalidate the session. + * @details The credential storage object, or nil to indicate that no credential storage is to be used * @return The converted Objective-C result. */ URLCredentialStorage url_credential_storage() const; /** * @brief Sets the `URLCredentialStorage` property of `NSURLSessionConfiguration`. - * @details A credential store that provides credentials for authentication. To not use a credential store, set this property to 'nil'. For default and background sessions, the default value is the shared credential storage object. For ephemeral sessions, the default value is a private credential store object that stores data in memory only, and is destroyed when you invalidate the session. + * @details The credential storage object, or nil to indicate that no credential storage is to be used * @param value Argument converted to the Objective-C parameter of the same role. */ void set_url_credential_storage(const URLCredentialStorage& value) const; /** * @brief Returns the `allowsCellularAccess` property of `NSURLSessionConfiguration`. - * @details A Boolean value that determines whether connections should be made over a cellular network. This property controls whether tasks in sessions based on this session configuration are allowed to make connections over a cellular network. The default value is 'YES'. + * @details allow request to route over cellular. * @return The converted Objective-C result. */ bool allows_cellular_access() const; /** * @brief Sets the `allowsCellularAccess` property of `NSURLSessionConfiguration`. - * @details A Boolean value that determines whether connections should be made over a cellular network. This property controls whether tasks in sessions based on this session configuration are allowed to make connections over a cellular network. The default value is 'YES'. + * @details allow request to route over cellular. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_cellular_access(bool value) const; /** * @brief Returns the `allowsConstrainedNetworkAccess` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether connections may use the network when the user has specified Low Data Mode. The default value is 'YES'. + * @details allow request to route over networks in constrained mode. Defaults to YES. * @return The converted Objective-C result. */ bool allows_constrained_network_access() const; /** * @brief Sets the `allowsConstrainedNetworkAccess` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether connections may use the network when the user has specified Low Data Mode. The default value is 'YES'. + * @details allow request to route over networks in constrained mode. Defaults to YES. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_constrained_network_access(bool value) const; /** * @brief Returns the `allowsExpensiveNetworkAccess` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether connections may use a network interface that the system considers expensive. The default value is 'YES'. + * @details allow request to route over expensive networks. Defaults to YES. * @return The converted Objective-C result. */ bool allows_expensive_network_access() const; /** * @brief Sets the `allowsExpensiveNetworkAccess` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether connections may use a network interface that the system considers expensive. The default value is 'YES'. + * @details allow request to route over expensive networks. Defaults to YES. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allows_expensive_network_access(bool value) const; @@ -236,31 +235,30 @@ namespace cocoon void set_allows_ultra_constrained_network_access(bool value) const; /** * @brief Returns the `connectionProxyDictionary` property of `NSURLSessionConfiguration`. - * @details A dictionary containing information about the proxy to use within this session. Prefer using 'proxyConfigurations', which supports secure proxy and relay types. The default value is 'NULL', which means that tasks use the default system settings. + * @details The proxy dictionary, as described by \ * @return The converted Objective-C result. */ std::vector> connection_proxy_dictionary() const; /** * @brief Sets the `connectionProxyDictionary` property of `NSURLSessionConfiguration`. - * @details A dictionary containing information about the proxy to use within this session. Prefer using 'proxyConfigurations', which supports secure proxy and relay types. The default value is 'NULL', which means that tasks use the default system settings. + * @details The proxy dictionary, as described by \ * @param value Argument converted to the Objective-C parameter of the same role. */ void set_connection_proxy_dictionary(const std::vector>& value) const; /** * @brief Returns the `defaultSessionConfiguration` property of `NSURLSessionConfiguration`. - * @details A default session configuration object. The default session configuration uses a persistent disk-based cache (except when the result is downloaded to a file) and stores credentials in the user's keychain. It also stores cookies (by default) in the same shared cookie store as 'NSURLConnection' and 'NSURLDownload'. Modifying the returned session configuration object does not affect any configuration objects returned by future calls to this method, and does not change the default behavior for existing sessions. It is therefore always safe to use the returned object as a starting point for additional customization. * @return The converted Objective-C result. */ static URLSessionConfiguration default_session_configuration(); /** * @brief Returns the `discretionary` property of `NSURLSessionConfiguration`. - * @details A Boolean value that determines whether background tasks can be scheduled at the discretion of the system for optimal performance. For configuration objects created using '+backgroundSessionConfigurationWithIdentifier:', use this property to give the system control over when transfers should occur. This property is ignored for configuration objects created using other methods. When transferring large amounts of data, you are encouraged to set this to 'YES'. Doing so lets the system schedule those transfers at times that are more optimal for the device. The default value is 'NO'. + * @details allows background tasks to be scheduled at the discretion of the system for optimal performance. * @return The converted Objective-C result. */ bool is_discretionary() const; /** * @brief Sets the `discretionary` property of `NSURLSessionConfiguration`. - * @details A Boolean value that determines whether background tasks can be scheduled at the discretion of the system for optimal performance. For configuration objects created using '+backgroundSessionConfigurationWithIdentifier:', use this property to give the system control over when transfers should occur. This property is ignored for configuration objects created using other methods. When transferring large amounts of data, you are encouraged to set this to 'YES'. Doing so lets the system schedule those transfers at times that are more optimal for the device. The default value is 'NO'. + * @details allows background tasks to be scheduled at the discretion of the system for optimal performance. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_discretionary(bool value) const; @@ -278,49 +276,48 @@ namespace cocoon void set_enables_early_data(bool value) const; /** * @brief Returns the `ephemeralSessionConfiguration` property of `NSURLSessionConfiguration`. - * @details A session configuration that uses no persistent storage for caches, cookies, or credentials. An ephemeral session configuration object is similar to a default session configuration (see 'defaultSessionConfiguration'), except that the corresponding session object doesn't store caches, credential stores, or any session-related data to disk. Instead, session-related data is stored in RAM. The only time an ephemeral session writes data to disk is when you tell it to write the contents of a URL to a file. The main advantage to using ephemeral sessions is privacy. By not writing potentially sensitive data to disk, you make it less likely that the data will be intercepted and used later. For this reason, ephemeral sessions are ideal for private browsing modes in web browsers and other similar situations. When your app invalidates the session, all ephemeral session data is purged automatically. Additionally, in iOS, the in-memory cache isn't purged automatically when your app is suspended but may be purged when your app is terminated or when the system experiences memory pressure. * @return The converted Objective-C result. */ static URLSessionConfiguration ephemeral_session_configuration(); /** * @brief Returns the `identifier` property of `NSURLSessionConfiguration`. - * @details The background session identifier of the configuration object. The value of this property is set only when you use '+backgroundSessionConfigurationWithIdentifier:' to create the configuration object. The string uniquely identifies a background session object. In iOS, you use this string in cases where the app was terminated while transfers were occurring in the background. When the app relaunches, it uses the string to recreate the configuration and session objects associated with the transfers. + * @details identifier for the background session configuration * @return The converted Objective-C result. */ std::string identifier() const; /** * @brief Returns the `networkServiceType` property of `NSURLSessionConfiguration`. - * @details The type of network service for all tasks within network sessions to enable Cellular Network Slicing. + * @details type of service for requests. * @return The converted Objective-C result. */ URLRequestNetworkServiceType network_service_type() const; /** * @brief Sets the `networkServiceType` property of `NSURLSessionConfiguration`. - * @details The type of network service for all tasks within network sessions to enable Cellular Network Slicing. + * @details type of service for requests. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_network_service_type(URLRequestNetworkServiceType value) const; /** * @brief Returns the `protocolClasses` property of `NSURLSessionConfiguration`. - * @details An array of extra protocol subclasses that handle requests in a session. Use this array to extend the default set of common networking protocols available for use by a session with one or more custom protocols that you define. You should not use '+[NSURLProtocol registerClass:]', as that method will register your class with the default session rather than with an instance of 'NSURLSession'. > Note: You cannot use custom 'NSURLProtocol' subclasses in conjunction with background > sessions. + * @details An optional array of Class objects which subclass NSURLProtocol. The Class will be sent +canInitWithRequest: when determining if an instance of the class can be used for a given URL scheme. You should not use +[NSURLProtocol registerClass:], as that method will register your class with the default session rather than with an instance of NSURLSession. Custom NSURLProtocol subclasses are not available to background sessions. * @return The converted Objective-C result. */ std::vector protocol_classes() const; /** * @brief Sets the `protocolClasses` property of `NSURLSessionConfiguration`. - * @details An array of extra protocol subclasses that handle requests in a session. Use this array to extend the default set of common networking protocols available for use by a session with one or more custom protocols that you define. You should not use '+[NSURLProtocol registerClass:]', as that method will register your class with the default session rather than with an instance of 'NSURLSession'. > Note: You cannot use custom 'NSURLProtocol' subclasses in conjunction with background > sessions. + * @details An optional array of Class objects which subclass NSURLProtocol. The Class will be sent +canInitWithRequest: when determining if an instance of the class can be used for a given URL scheme. You should not use +[NSURLProtocol registerClass:], as that method will register your class with the default session rather than with an instance of NSURLSession. Custom NSURLProtocol subclasses are not available to background sessions. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_protocol_classes(const std::vector& value) const; /** * @brief Returns the `requestCachePolicy` property of `NSURLSessionConfiguration`. - * @details A predefined constant that determines when to return a response from the cache. This property determines the request caching policy used by tasks within sessions based on this configuration. The default value is 'NSURLRequestUseProtocolCachePolicy'. + * @details default cache policy for requests * @return The converted Objective-C result. */ URLRequestCachePolicy request_cache_policy() const; /** * @brief Sets the `requestCachePolicy` property of `NSURLSessionConfiguration`. - * @details A predefined constant that determines when to return a response from the cache. This property determines the request caching policy used by tasks within sessions based on this configuration. The default value is 'NSURLRequestUseProtocolCachePolicy'. + * @details default cache policy for requests * @param value Argument converted to the Objective-C parameter of the same role. */ void set_request_cache_policy(URLRequestCachePolicy value) const; @@ -338,49 +335,49 @@ namespace cocoon void set_requires_dnssec_validation(bool value) const; /** * @brief Returns the `sessionSendsLaunchEvents` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether the app should be resumed or launched in the background when transfers finish. For configuration objects created using '+backgroundSessionConfigurationWithIdentifier:', you can use this property to control the launching behavior for an iOS app. This property is ignored for configuration objects created using other methods. The default value is 'YES'. When 'YES', the system automatically wakes up or launches the iOS app in the background when the session's tasks finish or require authentication. > Note: macOS apps based on AppKit do not support background launch. + * @details Allows the app to be resumed or launched in the background when tasks in background sessions complete or when auth is required. This only applies to configurations created with +backgroundSessionConfigurationWithIdentifier: and the default value is YES. NOTE: macOS apps based on AppKit do not support background launch. * @return The converted Objective-C result. */ bool session_sends_launch_events() const; /** * @brief Sets the `sessionSendsLaunchEvents` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether the app should be resumed or launched in the background when transfers finish. For configuration objects created using '+backgroundSessionConfigurationWithIdentifier:', you can use this property to control the launching behavior for an iOS app. This property is ignored for configuration objects created using other methods. The default value is 'YES'. When 'YES', the system automatically wakes up or launches the iOS app in the background when the session's tasks finish or require authentication. > Note: macOS apps based on AppKit do not support background launch. + * @details Allows the app to be resumed or launched in the background when tasks in background sessions complete or when auth is required. This only applies to configurations created with +backgroundSessionConfigurationWithIdentifier: and the default value is YES. NOTE: macOS apps based on AppKit do not support background launch. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_session_sends_launch_events(bool value) const; /** * @brief Returns the `sharedContainerIdentifier` property of `NSURLSessionConfiguration`. - * @details The identifier for the shared container into which files in background URL sessions should be downloaded. To create a URL session for use by an app extension, set this property to a valid identifier for a container shared between the app extension and its containing app. > Important: If you try to create a URL session from your app extension but fail to set > this property to a valid value, the URL session is invalidated upon creation. + * @details The identifier of the shared data container into which files in background sessions should be downloaded. App extensions wishing to use background sessions must set this property to a valid container identifier, or all transfers in that session will fail with NSURLErrorBackgroundSessionRequiresSharedContainer. * @return The converted Objective-C result. */ std::string shared_container_identifier() const; /** * @brief Sets the `sharedContainerIdentifier` property of `NSURLSessionConfiguration`. - * @details The identifier for the shared container into which files in background URL sessions should be downloaded. To create a URL session for use by an app extension, set this property to a valid identifier for a container shared between the app extension and its containing app. > Important: If you try to create a URL session from your app extension but fail to set > this property to a valid value, the URL session is invalidated upon creation. + * @details The identifier of the shared data container into which files in background sessions should be downloaded. App extensions wishing to use background sessions must set this property to a valid container identifier, or all transfers in that session will fail with NSURLErrorBackgroundSessionRequiresSharedContainer. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_shared_container_identifier(const std::string& value) const; /** * @brief Returns the `timeoutIntervalForRequest` property of `NSURLSessionConfiguration`. - * @details The timeout interval to use when waiting for additional data. This property determines the request timeout interval for all tasks within sessions based on this configuration. The request timeout interval controls how long (in seconds) a task should wait for additional data to arrive before giving up. The timer associated with this value is reset whenever new data arrives. When the request timer reaches the specified interval without receiving any new data, it triggers a timeout. The default value is '60'. > Important: Any upload or download tasks created by a background session are automatically > retried if the original request fails due to a timeout. To configure how long an upload > or download task should be allowed to be retried or transferred, use the > 'timeoutIntervalForResource' property. + * @details default timeout for requests. This will cause a timeout if no data is transmitted for the given timeout value, and is reset whenever data is transmitted. * @return The converted Objective-C result. */ double timeout_interval_for_request() const; /** * @brief Sets the `timeoutIntervalForRequest` property of `NSURLSessionConfiguration`. - * @details The timeout interval to use when waiting for additional data. This property determines the request timeout interval for all tasks within sessions based on this configuration. The request timeout interval controls how long (in seconds) a task should wait for additional data to arrive before giving up. The timer associated with this value is reset whenever new data arrives. When the request timer reaches the specified interval without receiving any new data, it triggers a timeout. The default value is '60'. > Important: Any upload or download tasks created by a background session are automatically > retried if the original request fails due to a timeout. To configure how long an upload > or download task should be allowed to be retried or transferred, use the > 'timeoutIntervalForResource' property. + * @details default timeout for requests. This will cause a timeout if no data is transmitted for the given timeout value, and is reset whenever data is transmitted. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_timeout_interval_for_request(double value) const; /** * @brief Returns the `timeoutIntervalForResource` property of `NSURLSessionConfiguration`. - * @details The maximum amount of time that a resource request should be allowed to take. This property determines the resource timeout interval for all tasks within sessions based on this configuration. The resource timeout interval controls how long (in seconds) to wait for an entire resource to transfer before giving up. The resource timer starts when the request is initiated and counts until either the request completes or this timeout interval is reached, whichever comes first. The default value is 7 days. + * @details default timeout for requests. This will cause a timeout if a resource is not able to be retrieved within a given timeout. * @return The converted Objective-C result. */ double timeout_interval_for_resource() const; /** * @brief Sets the `timeoutIntervalForResource` property of `NSURLSessionConfiguration`. - * @details The maximum amount of time that a resource request should be allowed to take. This property determines the resource timeout interval for all tasks within sessions based on this configuration. The resource timeout interval controls how long (in seconds) to wait for an entire resource to transfer before giving up. The resource timer starts when the request is initiated and counts until either the request completes or this timeout interval is reached, whichever comes first. The default value is 7 days. + * @details default timeout for requests. This will cause a timeout if a resource is not able to be retrieved within a given timeout. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_timeout_interval_for_resource(double value) const; @@ -398,13 +395,13 @@ namespace cocoon void set_uses_classic_loading_mode(bool value) const; /** * @brief Returns the `waitsForConnectivity` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately. Connectivity might be temporarily unavailable for several reasons. For example, a device might only have a cellular connection when 'allowsCellularAccess' is set to 'NO', or the device might require a VPN connection but none is available. If the value of this property is 'YES' and sufficient connectivity is unavailable, the session calls the 'URLSession:taskIsWaitingForConnectivity:' delegate method and waits for connectivity. If the value is 'NO' and connectivity is unavailable, the connection fails immediately with an error. Default value is 'NO'. Ignored by background sessions, as background sessions always wait for connectivity. + * @details Causes tasks to wait for network connectivity to become available, rather than immediately failing with an error (such as NSURLErrorNotConnectedToInternet) when it is not. When waiting for connectivity, the timeoutIntervalForRequest property does not apply, but the timeoutIntervalForResource property does. Unsatisfactory connectivity (that requires waiting) includes cases where the device has limited or insufficient connectivity for a task (e.g., only has a cellular connection but the allowsCellularAccess property is NO, or requires a VPN connection in order to reach the desired host). Default value is NO. Ignored by background sessions, as background sessions always wait for connectivity. * @return The converted Objective-C result. */ bool waits_for_connectivity() const; /** * @brief Sets the `waitsForConnectivity` property of `NSURLSessionConfiguration`. - * @details A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately. Connectivity might be temporarily unavailable for several reasons. For example, a device might only have a cellular connection when 'allowsCellularAccess' is set to 'NO', or the device might require a VPN connection but none is available. If the value of this property is 'YES' and sufficient connectivity is unavailable, the session calls the 'URLSession:taskIsWaitingForConnectivity:' delegate method and waits for connectivity. If the value is 'NO' and connectivity is unavailable, the connection fails immediately with an error. Default value is 'NO'. Ignored by background sessions, as background sessions always wait for connectivity. + * @details Causes tasks to wait for network connectivity to become available, rather than immediately failing with an error (such as NSURLErrorNotConnectedToInternet) when it is not. When waiting for connectivity, the timeoutIntervalForRequest property does not apply, but the timeoutIntervalForResource property does. Unsatisfactory connectivity (that requires waiting) includes cases where the device has limited or insufficient connectivity for a task (e.g., only has a cellular connection but the allowsCellularAccess property is NO, or requires a VPN connection in order to reach the desired host). Default value is NO. Ignored by background sessions, as background sessions always wait for connectivity. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_waits_for_connectivity(bool value) const; diff --git a/include/generated/url_session_data_task.h b/include/generated/url_session_data_task.h index 7365b02b..19f4df04 100644 --- a/include/generated/url_session_data_task.h +++ b/include/generated/url_session_data_task.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSURLSessionDataTask` (Foundation). - * @details A URL session task that returns downloaded data directly to the app in memory. A ''URLSessionDataTask'' is a concrete subclass of ''URLSessionTask''. The methods in the ''URLSessionDataTask'' class are documented in ''URLSessionTask''. A data task returns data directly to the app (in memory) as one or more 'NSData' objects. When you use a data task: - During upload of the body data (if your app provides any), the session periodically calls its delegate's ''URLSessionTaskDelegate/urlSession(:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:)'' method with status information. - After receiving an initial response, the session calls its delegate's ''URLSessionDataDelegate/urlSession(:dataTask:didReceive:completionHandler:)'' method to let you examine the status code and headers, and optionally convert the data task into a download task. - During the transfer, the session calls its delegate's ''URLSessionDataDelegate/urlSession(:dataTask:didReceive:)'' method to provide your app with the content as it arrives. - Upon completion, the session calls its delegate's ''URLSessionDataDelegate/urlSession(:dataTask:willCacheResponse:completionHandler:)'' method to let you determine whether the response should be cached. For examples of using data tasks for fetching and uploading data, see \ and \. + * @details An NSURLSessionDataTask does not provide any additional functionality over an NSURLSessionTask and its presence is merely to provide lexical differentiation from download and upload tasks. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref URLSessionTask. * diff --git a/include/generated/url_session_download_task.h b/include/generated/url_session_download_task.h index 81db8c72..e69deb67 100644 --- a/include/generated/url_session_download_task.h +++ b/include/generated/url_session_download_task.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSURLSessionDownloadTask` (Foundation). - * @details A URL session task that stores downloaded data to a file. An ''URLSessionDownloadTask'' is a concrete subclass of ''URLSessionTask'', which provides most of the methods for this class. Download tasks directly write the server's response data to a temporary file, providing your app with progress updates as data arrives from the server. When you use download tasks in background sessions, these downloads continue even when your app is in the suspended state or otherwise not running. You can pause (cancel) download tasks and resume them later (assuming the server supports doing so). You can also resume downloads that failed because of network connectivity problems. \#\#\# Download delegate behavior When you use a download task, your delegate receives several callbacks unique to download scenarios. - During download, the session periodically calls the delegate's ''URLSessionDownloadDelegate/urlSession(:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite:)'' method with status information. - Upon successful completion, the session calls the delegate's ''URLSessionDownloadDelegate/urlSession(:downloadTask:didFinishDownloadingTo:)'' method or completion handler. In that method, you must either open the file for reading or move it to a permanent location in your app's sandbox container directory. - Upon unsuccessful completion, the session calls the delegate's ''URLSessionTaskDelegate/urlSession(:task:didCompleteWithError:)'' method or completion handler. The only errors your delegate receives through the 'error' parameter are client-side errors, such as being unable to resolve the hostname or connect to the host. To check for server-side errors, inspect the ''URLSessionTask/response'' property of the 'task' parameter received by this callback. + * @details NSURLSessionDownloadTask is a task that represents a download to local storage. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref URLSessionTask. * @@ -33,7 +33,7 @@ namespace cocoon explicit URLSessionDownloadTask(Adopt adopt); /** * @brief Calls `-[NSURLSessionDownloadTask cancelByProducingResumeData:]`. - * @details Cancels a download and calls the completion handler with resume data for later use. If conditions will allow for resuming the download in the future, the callback will be called with an opaque data blob, which may be used with '-downloadTaskWithResumeData:' to attempt to resume the download. If resume data cannot be created, the completion handler will be called with 'nil' resumeData. - Parameter completionHandler: The completion handler to call when the cancel operation is complete. The 'resumeData' parameter contains data that can be used to resume the download at a later time, or 'nil' if resuming is not possible. + * @details Cancel the download (and calls the superclass -cancel). If conditions will allow for resuming the download in the future, the callback will be called with an opaque data blob, which may be used with -downloadTaskWithResumeData: to attempt to resume the download. If resume data cannot be created, the completion handler will be called with nil resumeData. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void cancel_by_producing_resume_data(std::function)> completion_handler) const; diff --git a/include/generated/url_session_stream_task.h b/include/generated/url_session_stream_task.h index c79f6031..246da32b 100644 --- a/include/generated/url_session_stream_task.h +++ b/include/generated/url_session_stream_task.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLSessionStreamTask` (Foundation). - * @details A URL session task that is stream-based. ''URLSessionStreamTask'' is a concrete subclass of ''URLSessionTask''. Many of the methods in the ''URLSessionStreamTask'' class are documented in ''URLSessionTask''. The ''URLSessionStreamTask'' class provides an interface a TCP/IP connection created via ''URLSession''. Tasks may be created from an ''URLSession'' using the ''URLSession/streamTask(withHostName:port:)'' and ''URLSession/streamTask(with:)'' methods. They may also be created as a result of an ''URLSessionDataTask'' being upgraded via the HTTP 'Upgrade:' response header and appropriate use of the ''URLSessionConfiguration/httpShouldUsePipelining'' option of ''URLSessionConfiguration''. > Note: > See [RFC 2817](https://tools.ietf.org/html/rfc2817) and [RFC 6455](https://tools.ietf.org/html/rfc6455) for information about the 'Upgrade:' header. A ''URLSessionStreamTask'' object performs asynchronous reads and writes, which are enqueued and executed serially, calling a handler upon completion being on the session delegate queue. If the task is canceled, all enqueued reads and writes will call their completion handlers with an appropriate error. When working with APIs that accept ''Stream'' objects, you can create ''InputStream'' and ''OutputStream'' objects from an ''URLSessionStreamTask'' object by calling the ''captureStreams()'' method. > Note: > watchOS supports ''URLSessionStreamTask'' for specific use cases. For more details, see \. + * @details An NSURLSessionStreamTask provides an interface to perform reads and writes to a TCP/IP stream created via NSURLSession. This task may be explicitly created from an NSURLSession, or created as a result of the appropriate disposition response to a -URLSession:dataTask:didReceiveResponse: delegate message. NSURLSessionStreamTask can be used to perform asynchronous reads and writes. Reads and writes are enqueued and executed serially, with the completion handler being invoked on the sessions delegate queue. If an error occurs, or the task is canceled, all outstanding read and write calls will have their completion handlers invoked with an appropriate error. It is also possible to create NSInputStream and NSOutputStream instances from an NSURLSessionTask by sending -captureStreams to the task. All outstanding reads and writes are completed before the streams are created. Once the streams are delivered to the session delegate, the task is considered complete and will receive no more messages. These streams are disassociated from the underlying session. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref URLSessionTask. * @@ -44,22 +44,22 @@ namespace cocoon explicit URLSessionStreamTask(Adopt adopt); /** * @brief Calls `-[NSURLSessionStreamTask captureStreams]`. - * @details Completes any already enqueued reads and writes, then invokes the 'URLSession:streamTask:didBecomeInputStream:outputStream:' delegate message. When that message is received, the task object is considered completed and will not receive any more delegate messages. + * @details -captureStreams completes any already enqueued reads and writes, and then invokes the URLSession:streamTask:didBecomeInputStream:outputStream: delegate message. When that message is received, the task object is considered completed and will not receive any more delegate messages. */ void capture_streams() const; /** * @brief Calls `-[NSURLSessionStreamTask closeRead]`. - * @details Enqueues a request to close the read side of the underlying socket. All outstanding IO will complete before the read side is closed. You may continue writing to the server. + * @details Enqueue a request to close the read side of the underlying socket. All outstanding IO will complete before the read side is closed. You may continue writing to the server. */ void close_read() const; /** * @brief Calls `-[NSURLSessionStreamTask closeWrite]`. - * @details Enqueues a request to close the write end of the underlying socket. All outstanding IO will complete before the write side of the socket is closed. The server, however, may continue to write bytes back to the client, so best practice is to continue reading from the server until you receive EOF. + * @details Enqueue a request to close the write end of the underlying socket. All outstanding IO will complete before the write side of the socket is closed. The server, however, may continue to write bytes back to the client, so best practice is to continue reading from the server until you receive EOF. */ void close_write() const; /** * @brief Calls `-[NSURLSessionStreamTask readDataOfMinLength:maxLength:timeout:completionHandler:]`. - * @details Reads minimum 'minBytes', or at most 'maxBytes' bytes and invokes the completion handler on the session's delegate queue with the data or an error. If an error occurs, any outstanding reads will also fail, and new read requests will error out immediately. - Parameter minBytes: The minimum number of bytes to read. - Parameter maxBytes: The maximum number of bytes to read. - Parameter timeout: The timeout interval for the read operation. - Parameter completionHandler: The completion handler to call when the read operation completes. + * @details Read minBytes, or at most maxBytes bytes and invoke the completion handler on the sessions delegate queue with the data or an error. If an error occurs, any outstanding reads will also fail, and new read requests will error out immediately. * @param min_bytes Argument converted to the Objective-C parameter of the same role. * @param max_bytes Argument converted to the Objective-C parameter of the same role. * @param timeout Argument converted to the Objective-C parameter of the same role. @@ -68,12 +68,12 @@ namespace cocoon void read_data_of_min_length(std::uint64_t min_bytes, std::uint64_t max_bytes, double timeout, std::function, bool, Error)> completion_handler) const; /** * @brief Calls `-[NSURLSessionStreamTask startSecureConnection]`. - * @details Begins encrypted handshake. The handshake begins after all pending IO has completed. TLS authentication callbacks are sent to the session's 'URLSession:task:didReceiveChallenge:completionHandler:' delegate method. + * @details Begin encrypted handshake. The handshake begins after all pending IO has completed. TLS authentication callbacks are sent to the session's -URLSession:task:didReceiveChallenge:completionHandler: */ void start_secure_connection() const; /** * @brief Calls `-[NSURLSessionStreamTask writeData:timeout:completionHandler:]`. - * @details Writes the data completely to the underlying socket. If all the bytes have not been written by the timeout, a timeout error will occur. Note that invocation of the completion handler does not guarantee that the remote side has received all the bytes, only that they have been written to the kernel. - Parameter data: The data to write to the stream. - Parameter timeout: The timeout interval for the write operation. - Parameter completionHandler: The completion handler to call when the write operation completes. + * @details Write the data completely to the underlying socket. If all the bytes have not been written by the timeout, a timeout error will occur. Note that invocation of the completion handler does not guarantee that the remote side has received all the bytes, only that they have been written to the kernel. * @param data Argument converted to the Objective-C parameter of the same role. * @param timeout Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. diff --git a/include/generated/url_session_task.h b/include/generated/url_session_task.h index 3b3b4c97..d3436804 100644 --- a/include/generated/url_session_task.h +++ b/include/generated/url_session_task.h @@ -21,7 +21,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLSessionTask` (Foundation). - * @details A task, like downloading a specific resource, performed in a URL session. The ''URLSessionTask'' class is the base class for tasks in a URL session. Tasks are always part of a session; you create a task by calling one of the task creation methods on a ''URLSession'' instance. The method you call determines the type of task. - Use ''URLSession'''s ''URLSession/dataTask(with:)-10dy7'' and related methods to create ''URLSessionDataTask'' instances. Data tasks request a resource, returning the server's response as one or more 'NSData' objects in memory. They are supported in default, ephemeral, and shared sessions, but are not supported in background sessions. - Use ''URLSession'''s ''URLSession/uploadTask(with:from:)'' and related methods to create ''URLSessionUploadTask'' instances. Upload tasks are like data tasks, except that they make it easier to provide a request body so you can upload data before retrieving the server's response. Additionally, upload tasks are supported in background sessions. - Use ''URLSession'''s ''URLSession/downloadTask(with:)-1onj'' and related methods to create ''URLSessionDownloadTask'' instances. Download tasks download a resource directly to a file on disk. Download tasks are supported in any type of session. - Use ''URLSession'''s ''URLSession/streamTask(withHostName:port:)'' or ''URLSession/streamTask(with:)'' to create ''URLSessionStreamTask'' instances. Stream tasks establish a TCP/IP connection from a host name and port or a net service object. After you create a task, you start it by calling its ''resume()'' method. The session then maintains a strong reference to the task until the request finishes or fails; you don't need to maintain a reference to the task unless it's useful for your app's internal bookkeeping. > Note: > All task properties support key-value observing. + * @details NSURLSessionTask - a cancelable object that refers to the lifetime of processing a given request. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -63,154 +63,150 @@ namespace cocoon explicit URLSessionTask(Adopt adopt); /** * @brief Calls `-[NSURLSessionTask cancel]`. - * @details Cancels the task. This method returns immediately, marking the task as being canceled. Once a task is marked as being canceled, 'URLSession:task:didCompleteWithError:' will be sent to the task delegate, passing an error in the domain 'NSURLErrorDomain' with the code 'NSURLErrorCancelled'. A task may, under some circumstances, send messages to its delegate before the cancelation is acknowledged. This method may be called on a task that is suspended. + * @details -cancel returns immediately, but marks a task as being canceled. The task will signal -URLSession:task:didCompleteWithError: with an error value of { NSURLErrorDomain, NSURLErrorCancelled }. In some cases, the task may signal other work before it acknowledges the cancelation. -cancel may be sent to a task that has been suspended. */ void cancel() const; /** * @brief Calls `-[NSURLSessionTask resume]`. - * @details Resumes the task, if it is suspended. Newly-initialized tasks begin in a suspended state, so you need to call this method to start the task. */ void resume() const; /** * @brief Calls `-[NSURLSessionTask suspend]`. - * @details Temporarily suspends the task. Suspending a task will prevent the 'NSURLSession' from continuing to load data. There may still be delegate calls made on behalf of this task (for instance, to report data received while suspending) but no further transmissions will be made on behalf of the task until '-resume' is sent. The timeout timer associated with the task will be disabled while a task is suspended. '-suspend' and '-resume' are nestable. + * @details Suspending a task will prevent the NSURLSession from continuing to load data. There may still be delegate calls made on behalf of this task (for instance, to report data received while suspending) but no further transmissions will be made on behalf of the task until -resume is sent. The timeout timer associated with the task will be disabled while a task is suspended. -suspend and -resume are nestable. */ void suspend() const; /** * @brief Returns the `countOfBytesClientExpectsToReceive` property of `NSURLSessionTask`. - * @details A best-guess upper bound on the number of bytes the client expects to receive. The value set for this property should account for the size of both HTTP response headers and the response body. If no value is specified, the system uses 'NSURLSessionTransferSizeUnknown' instead. This property is used by the system to optimize the scheduling of URL session tasks. Developers are strongly encouraged to provide an approximate upper bound, or an exact byte count, if possible, rather than accept the default. * @return The converted Objective-C result. */ std::int64_t count_of_bytes_client_expects_to_receive() const; /** * @brief Sets the `countOfBytesClientExpectsToReceive` property of `NSURLSessionTask`. - * @details A best-guess upper bound on the number of bytes the client expects to receive. The value set for this property should account for the size of both HTTP response headers and the response body. If no value is specified, the system uses 'NSURLSessionTransferSizeUnknown' instead. This property is used by the system to optimize the scheduling of URL session tasks. Developers are strongly encouraged to provide an approximate upper bound, or an exact byte count, if possible, rather than accept the default. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_count_of_bytes_client_expects_to_receive(std::int64_t value) const; /** * @brief Returns the `countOfBytesClientExpectsToSend` property of `NSURLSessionTask`. - * @details A best-guess upper bound on the number of bytes the client expects to send. The value set for this property should account for the size of HTTP headers and body data or body stream. If no value is specified, the system uses 'NSURLSessionTransferSizeUnknown' instead. This property is used by the system to optimize the scheduling of URL session tasks. Developers are strongly encouraged to provide an approximate upper bound, or an exact byte count, if possible, rather than accept the default. + * @details The number of bytes that the client expects (a best-guess upper-bound) will be sent and received by this task. These values are used by system scheduling policy. If unspecified, NSURLSessionTransferSizeUnknown is used. * @return The converted Objective-C result. */ std::int64_t count_of_bytes_client_expects_to_send() const; /** * @brief Sets the `countOfBytesClientExpectsToSend` property of `NSURLSessionTask`. - * @details A best-guess upper bound on the number of bytes the client expects to send. The value set for this property should account for the size of HTTP headers and body data or body stream. If no value is specified, the system uses 'NSURLSessionTransferSizeUnknown' instead. This property is used by the system to optimize the scheduling of URL session tasks. Developers are strongly encouraged to provide an approximate upper bound, or an exact byte count, if possible, rather than accept the default. + * @details The number of bytes that the client expects (a best-guess upper-bound) will be sent and received by this task. These values are used by system scheduling policy. If unspecified, NSURLSessionTransferSizeUnknown is used. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_count_of_bytes_client_expects_to_send(std::int64_t value) const; /** * @brief Returns the `countOfBytesExpectedToReceive` property of `NSURLSessionTask`. - * @details The number of bytes that the task expects to receive in the response body. This value is determined based on the 'Content-Length' header received from the server. If that header is absent, the value is 'NSURLSessionTransferSizeUnknown'. + * @details number of byte bytes we expect to receive, usually derived from the Content-Length header of an HTTP response. * @return The converted Objective-C result. */ std::int64_t count_of_bytes_expected_to_receive() const; /** * @brief Returns the `countOfBytesExpectedToSend` property of `NSURLSessionTask`. - * @details The number of bytes that the task expects to send in the request body. The URL loading system can determine the length of the upload data in three ways: - From the length of the data object provided as the upload body. - From the length of the file on disk provided as the upload body of an upload task (not a download task). - From the 'Content-Length' in the request object, if you explicitly set it. Otherwise, the value is 'NSURLSessionTransferSizeUnknown' ('-1') if you provided a stream or body data object, or zero ('0') if you did not. + * @details number of body bytes we expect to send, derived from the Content-Length of the HTTP request * @return The converted Objective-C result. */ std::int64_t count_of_bytes_expected_to_send() const; /** * @brief Returns the `countOfBytesReceived` property of `NSURLSessionTask`. - * @details The number of bytes that the task has received from the server in the response body. To be notified when this value changes, implement the 'URLSession:dataTask:didReceiveData:' delegate method (for data and upload tasks) or the 'URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite:' method (for download tasks). + * @details number of body bytes already received * @return The converted Objective-C result. */ std::int64_t count_of_bytes_received() const; /** * @brief Returns the `countOfBytesSent` property of `NSURLSessionTask`. - * @details The number of bytes that the task has sent to the server in the request body. This byte count includes only the length of the request body itself, not the request headers. To be notified when this value changes, implement the 'URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:' delegate method. + * @details number of body bytes already sent * @return The converted Objective-C result. */ std::int64_t count_of_bytes_sent() const; /** * @brief Returns the `currentRequest` property of `NSURLSessionTask`. - * @details The URL request object currently being handled by the task. This value is typically the same as the initial request ('originalRequest') except when the server has responded to the initial request with a redirect to a different URL. + * @details \@property (nullable, readonly, copy) NSURLRequest originalRequest; / may be nil if this is a stream task * @return The converted Objective-C result. */ URLRequest current_request() const; /** * @brief Returns the `earliestBeginDate` property of `NSURLSessionTask`. - * @details The earliest date at which the network load should begin. For tasks created from background 'NSURLSession' instances, this property indicates that the network load should not begin any earlier than this date. Setting this property does not guarantee that the load will begin at the specified date, but only that it will not begin sooner. If not specified, no start delay is used. This property has no effect for tasks created from nonbackground sessions. + * @details Start the network load for this task no earlier than the specified date. If not specified, no start delay is used. Only applies to tasks created from background NSURLSession instances; has no effect for tasks created from other session types. * @return The converted Objective-C result. */ Date earliest_begin_date() const; /** * @brief Sets the `earliestBeginDate` property of `NSURLSessionTask`. - * @details The earliest date at which the network load should begin. For tasks created from background 'NSURLSession' instances, this property indicates that the network load should not begin any earlier than this date. Setting this property does not guarantee that the load will begin at the specified date, but only that it will not begin sooner. If not specified, no start delay is used. This property has no effect for tasks created from nonbackground sessions. + * @details Start the network load for this task no earlier than the specified date. If not specified, no start delay is used. Only applies to tasks created from background NSURLSession instances; has no effect for tasks created from other session types. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_earliest_begin_date(const Date& value) const; /** * @brief Returns the `error` property of `NSURLSessionTask`. - * @details An error object that indicates why the task failed. This value is 'nil' if the task is still active or if the transfer completed successfully. + * @details The error, if any, delivered via -URLSession:task:didCompleteWithError: This property will be nil in the event that no error occurred. * @return The converted Objective-C result. */ Error error() const; /** * @brief Returns the `originalRequest` property of `NSURLSessionTask`. - * @details The original request object passed when the task was created. This value is typically the same as the currently active request ('currentRequest') except when the server has responded to the initial request with a redirect to a different URL. + * @details \@property (readonly) NSUInteger taskIdentifier; / an identifier for this task, assigned by and unique to the owning session * @return The converted Objective-C result. */ URLRequest original_request() const; /** * @brief Returns the `prefersIncrementalDelivery` property of `NSURLSessionTask`. - * @details A Boolean value that determines whether to deliver a partial response body in increments. Set this property to 'true' to tell the task that the app would benefit from receiving a partial response body in increments. If the app can't process the response until it has all the data, set this property to 'false'. Task performance may improve when this value is 'false', in which case the task only delivers data when complete. This property defaults to 'true', except in the following cases which default to 'false': - The task delivers results to a completion handler rather than to a delegate. - The task is a download task. + * @details Provides a hint indicating if incremental delivery of a partial response body would be useful for the application, or if it cannot process the response until it is complete. Indicating that incremental delivery is not desired may improve task performance. For example, if a response cannot be decoded until the entire content is received, set this property to false. Defaults to true unless this task is created with completion-handler based convenience methods, or if it is a download task. * @return The converted Objective-C result. */ bool prefers_incremental_delivery() const; /** * @brief Sets the `prefersIncrementalDelivery` property of `NSURLSessionTask`. - * @details A Boolean value that determines whether to deliver a partial response body in increments. Set this property to 'true' to tell the task that the app would benefit from receiving a partial response body in increments. If the app can't process the response until it has all the data, set this property to 'false'. Task performance may improve when this value is 'false', in which case the task only delivers data when complete. This property defaults to 'true', except in the following cases which default to 'false': - The task delivers results to a completion handler rather than to a delegate. - The task is a download task. + * @details Provides a hint indicating if incremental delivery of a partial response body would be useful for the application, or if it cannot process the response until it is complete. Indicating that incremental delivery is not desired may improve task performance. For example, if a response cannot be decoded until the entire content is received, set this property to false. Defaults to true unless this task is created with completion-handler based convenience methods, or if it is a download task. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_prefers_incremental_delivery(bool value) const; /** * @brief Returns the `priority` property of `NSURLSessionTask`. - * @details The relative priority at which you'd like a host to handle the task, specified as a floating point value between '0.0' (lowest priority) and '1.0' (highest priority). To provide hints to a host on how to prioritize URL session tasks from your app, specify a priority for each task. Specifying a priority provides only a hint and does not guarantee performance. If you don't specify a priority, a URL session task has a priority of 'NSURLSessionTaskPriorityDefault', with a value of '0.5'. There are three named priorities you can employ: 'NSURLSessionTaskPriorityDefault', 'NSURLSessionTaskPriorityLow', and 'NSURLSessionTaskPriorityHigh'. You can specify or change a task's priority at any time, but not all networking protocols respond to changes after a task has started. There is no API to let you determine the effective priority for a task from a host's perspective. + * @details Sets a scaling factor for the priority of the task. The scaling factor is a value between 0.0 and 1.0 (inclusive), where 0.0 is considered the lowest priority and 1.0 is considered the highest. The priority is a hint and not a hard requirement of task performance. The priority of a task may be changed using this API at any time, but not all protocols support this; in these cases, the last priority that took effect will be used. If no priority is specified, the task will operate with the default priority as defined by the constant NSURLSessionTaskPriorityDefault. Two additional priority levels are provided: NSURLSessionTaskPriorityLow and NSURLSessionTaskPriorityHigh, but use is not restricted to these. * @return The converted Objective-C result. */ float priority() const; /** * @brief Sets the `priority` property of `NSURLSessionTask`. - * @details The relative priority at which you'd like a host to handle the task, specified as a floating point value between '0.0' (lowest priority) and '1.0' (highest priority). To provide hints to a host on how to prioritize URL session tasks from your app, specify a priority for each task. Specifying a priority provides only a hint and does not guarantee performance. If you don't specify a priority, a URL session task has a priority of 'NSURLSessionTaskPriorityDefault', with a value of '0.5'. There are three named priorities you can employ: 'NSURLSessionTaskPriorityDefault', 'NSURLSessionTaskPriorityLow', and 'NSURLSessionTaskPriorityHigh'. You can specify or change a task's priority at any time, but not all networking protocols respond to changes after a task has started. There is no API to let you determine the effective priority for a task from a host's perspective. + * @details Sets a scaling factor for the priority of the task. The scaling factor is a value between 0.0 and 1.0 (inclusive), where 0.0 is considered the lowest priority and 1.0 is considered the highest. The priority is a hint and not a hard requirement of task performance. The priority of a task may be changed using this API at any time, but not all protocols support this; in these cases, the last priority that took effect will be used. If no priority is specified, the task will operate with the default priority as defined by the constant NSURLSessionTaskPriorityDefault. Two additional priority levels are provided: NSURLSessionTaskPriorityLow and NSURLSessionTaskPriorityHigh, but use is not restricted to these. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_priority(float value) const; /** * @brief Returns the `progress` property of `NSURLSessionTask`. - * @details A representation of the overall task progress. It can be used for task progress tracking. + * @details NSProgress object which represents the task progress. It can be used for task progress tracking. * @return The converted Objective-C result. */ Progress progress() const; /** * @brief Returns the `response` property of `NSURLSessionTask`. - * @details The server's response to the currently active request. This object provides information about the request as provided by the server. This information always includes the original URL. It may also include an expected length, MIME type information, encoding information, a suggested filename, or a combination of these. + * @details \@property (nullable, readonly, copy) NSURLRequest currentRequest; / may differ from originalRequest due to http server redirection * @return The converted Objective-C result. */ URLResponse response() const; /** * @brief Returns the `state` property of `NSURLSessionTask`. - * @details The current state of the task---active, suspended, in the process of being canceled, or completed. + * @details The current state of the task within the session. * @return The converted Objective-C result. */ URLSessionTaskState state() const; /** * @brief Returns the `taskDescription` property of `NSURLSessionTask`. - * @details An app-provided string value for the current task. The system doesn't interpret this value; use it for whatever purpose you see fit. For example, you could store a description of the task for debugging purposes, or a key to track the task in your own data structures. + * @details The taskDescription property is available for the developer to provide a descriptive label for the task. * @return The converted Objective-C result. */ std::string task_description() const; /** * @brief Sets the `taskDescription` property of `NSURLSessionTask`. - * @details An app-provided string value for the current task. The system doesn't interpret this value; use it for whatever purpose you see fit. For example, you could store a description of the task for debugging purposes, or a key to track the task in your own data structures. + * @details The taskDescription property is available for the developer to provide a descriptive label for the task. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_task_description(const std::string& value) const; /** * @brief Returns the `taskIdentifier` property of `NSURLSessionTask`. - * @details An identifier uniquely identifying the task within a given session. This value is unique only within the context of a single session; tasks in other sessions may have the same 'taskIdentifier' value. * @return The converted Objective-C result. */ std::uint64_t task_identifier() const; diff --git a/include/generated/url_session_task_metrics.h b/include/generated/url_session_task_metrics.h index d1d0077c..f4b0ae2b 100644 --- a/include/generated/url_session_task_metrics.h +++ b/include/generated/url_session_task_metrics.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLSessionTaskMetrics` (Foundation). - * @details An object encapsulating the metrics for a session task. Each ''URLSessionTaskMetrics'' object contains the ''taskInterval'' and ''redirectCount'', as well as metrics for each request-and-response transaction made during the execution of the task. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -35,7 +34,7 @@ namespace cocoon explicit URLSessionTaskMetrics(Adopt adopt); /** * @brief Returns the `redirectCount` property of `NSURLSessionTaskMetrics`. - * @details The number of redirects that were recorded. + * @details redirectCount is the number of redirects that were recorded. * @return The converted Objective-C result. */ std::uint64_t redirect_count() const; @@ -47,7 +46,7 @@ namespace cocoon DateInterval task_interval() const; /** * @brief Returns the `transactionMetrics` property of `NSURLSessionTaskMetrics`. - * @details An array containing the metrics collected for every request/response transaction created during the task execution. + * @details transactionMetrics array contains the metrics collected for every request/response transaction created during the task execution. * @return The converted Objective-C result. */ std::vector transaction_metrics() const; diff --git a/include/generated/url_session_task_transaction_metrics.h b/include/generated/url_session_task_transaction_metrics.h index 74ea9ab4..4491623a 100644 --- a/include/generated/url_session_task_transaction_metrics.h +++ b/include/generated/url_session_task_transaction_metrics.h @@ -15,7 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLSessionTaskTransactionMetrics` (Foundation). - * @details An object that encapsulates the performance metrics collected by the URL Loading System during the execution of a session task. Each ''URLSessionTaskTransactionMetrics'' object consists of a ''request'' and ''response'' property, corresponding to the request and response of the corresponding task. It also contains temporal metrics, starting with ''fetchStartDate'' and ending with ''responseEndDate'', as well as other characteristics like ''networkProtocolName'' and ''resourceFetchType''. \#\#\# Understanding temporal metrics The figure below shows the sequence of events for a URL session task, which correspond to the temporal metrics captured by ''URLSessionTaskTransactionMetrics''. ![Diagram showing the temporal metrics for a URL session task. When a task starts, it performs a DNS lookup and then starts a connection. If the connection is encrypted, the user agent starts a TLS security handshake to secure the connection. After the connection to the server is established, the user agent requests the specified resource, and receives a response.](media-3162616) For all metrics with a start and end date, if an aspect of the task was not completed, then its corresponding end date metric is 'nil'. This can happen if name lookup begins, but the operation either times out, fails, or the client cancels the task before the name can be resolved. In this case, the ''domainLookupEndDate'' property is 'nil', along with all metrics for aspects that occurred afterwards. \#\#\# Measuring tasks using iCloud Private Relay iCloud Private Relay can change the timing and sequence of events for your tasks by sending requests through a set of privacy proxies. All tasks that use iCloud Private Relay set the ''isProxyConnection'' property in their transaction metrics. In this case, the ''remoteAddress'' property contains the address of the proxy, and not the origin server. Tasks to different hosts can reuse the same transport connection, just like how tasks can already share a connection when using HTTP/2. In these cases, a proxied task may not report any ''secureConnectionStartDate'' or ''secureConnectionEndDate''. + * @details This class defines the performance metrics collected for a request/response transaction during the task execution. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -43,13 +43,13 @@ namespace cocoon bool is_cellular() const; /** * @brief Returns the `connectEndDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time immediately after the user agent finished establishing the connection to the server, including completion of security-related and other handshakes. + * @details connectEndDate is the time immediately after the user agent finished establishing the connection to the server, including completion of security-related and other handshakes. * @return The converted Objective-C result. */ Date connect_end_date() const; /** * @brief Returns the `connectStartDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time immediately before the user agent started establishing the connection to the server. For example, this would correspond to the time immediately before the user agent started trying to establish the TCP connection. + * @details connectStartDate is the time immediately before the user agent started establishing the connection to the server. For example, this would correspond to the time immediately before the user agent started trying to establish the TCP connection. * @return The converted Objective-C result. */ Date connect_start_date() const; @@ -61,49 +61,49 @@ namespace cocoon bool is_constrained() const; /** * @brief Returns the `countOfRequestBodyBytesBeforeEncoding` property of `NSURLSessionTaskTransactionMetrics`. - * @details The size of upload body data, file, or stream. + * @details countOfRequestBodyBytesBeforeEncoding is the size of upload body data, file, or stream. * @return The converted Objective-C result. */ std::int64_t count_of_request_body_bytes_before_encoding() const; /** * @brief Returns the `countOfRequestBodyBytesSent` property of `NSURLSessionTaskTransactionMetrics`. - * @details The number of bytes transferred for request body. It includes protocol-specific framing, transfer encoding, and content encoding. + * @details countOfRequestBodyBytesSent is the number of bytes transferred for request body. It includes protocol-specific framing, transfer encoding, and content encoding. * @return The converted Objective-C result. */ std::int64_t count_of_request_body_bytes_sent() const; /** * @brief Returns the `countOfRequestHeaderBytesSent` property of `NSURLSessionTaskTransactionMetrics`. - * @details The number of bytes transferred for request header. + * @details countOfRequestHeaderBytesSent is the number of bytes transferred for request header. * @return The converted Objective-C result. */ std::int64_t count_of_request_header_bytes_sent() const; /** * @brief Returns the `countOfResponseBodyBytesAfterDecoding` property of `NSURLSessionTaskTransactionMetrics`. - * @details The size of data delivered to your delegate or completion handler. + * @details countOfResponseBodyBytesAfterDecoding is the size of data delivered to your delegate or completion handler. * @return The converted Objective-C result. */ std::int64_t count_of_response_body_bytes_after_decoding() const; /** * @brief Returns the `countOfResponseBodyBytesReceived` property of `NSURLSessionTaskTransactionMetrics`. - * @details The number of bytes transferred for response body. It includes protocol-specific framing, transfer encoding, and content encoding. + * @details countOfResponseBodyBytesReceived is the number of bytes transferred for response header. It includes protocol-specific framing, transfer encoding, and content encoding. * @return The converted Objective-C result. */ std::int64_t count_of_response_body_bytes_received() const; /** * @brief Returns the `countOfResponseHeaderBytesReceived` property of `NSURLSessionTaskTransactionMetrics`. - * @details The number of bytes transferred for response header. + * @details countOfResponseHeaderBytesReceived is the number of bytes transferred for response header. * @return The converted Objective-C result. */ std::int64_t count_of_response_header_bytes_received() const; /** * @brief Returns the `domainLookupEndDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time after the name lookup was completed. + * @details domainLookupEndDate returns the time after the name lookup was completed. * @return The converted Objective-C result. */ Date domain_lookup_end_date() const; /** * @brief Returns the `domainLookupStartDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time immediately before the user agent started the name lookup for the resource. + * @details domainLookupStartDate returns the time immediately before the user agent started the name lookup for the resource. * @return The converted Objective-C result. */ Date domain_lookup_start_date() const; @@ -121,19 +121,19 @@ namespace cocoon bool is_expensive() const; /** * @brief Returns the `fetchStartDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time when the user agent started fetching the resource, whether or not the resource was retrieved from the server or local resources. The following metrics will be set to 'nil', if a persistent connection was used or the resource was retrieved from local resources: 'domainLookupStartDate', 'domainLookupEndDate', 'connectStartDate', 'connectEndDate', 'secureConnectionStartDate', 'secureConnectionEndDate'. + * @details fetchStartDate returns the time when the user agent started fetching the resource, whether or not the resource was retrieved from the server or local resources. The following metrics will be set to nil, if a persistent connection was used or the resource was retrieved from local resources: domainLookupStartDate domainLookupEndDate connectStartDate connectEndDate secureConnectionStartDate secureConnectionEndDate * @return The converted Objective-C result. */ Date fetch_start_date() const; /** * @brief Returns the `localAddress` property of `NSURLSessionTaskTransactionMetrics`. - * @details The IP address string of the local interface for the connection. For multipath protocols, this is the local address of the initial flow. If a connection was not used, this attribute is set to 'nil'. + * @details localAddress is the IP address string of the local interface for the connection. For multipath protocols, this is the local address of the initial flow. If a connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ std::string local_address() const; /** * @brief Returns the `localPort` property of `NSURLSessionTaskTransactionMetrics`. - * @details The port number of the local interface for the connection. For multipath protocols, this is the local port of the initial flow. If the app didn't use the connection, this value is 'nil'. + * @details localPort is the port number of the local interface for the connection. For multipath protocols, this is the local port of the initial flow. If a connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ Number local_port() const; @@ -145,37 +145,37 @@ namespace cocoon bool is_multipath() const; /** * @brief Returns the `negotiatedTLSCipherSuite` property of `NSURLSessionTaskTransactionMetrics`. - * @details The TLS cipher suite the task negotiated with the endpoint for the connection. This value is a 2-byte sequence in host byte order. See 'tls_ciphersuite_t' in 'Security/SecProtocolTypes.h' for possible values. If the task didn't negotiate an encrypted connection, this value is 'nil'. + * @details negotiatedTLSCipherSuite is the TLS cipher suite negotiated for the connection. It is a 2-byte sequence in host byte order. Please refer to tls_ciphersuite_t enum in Security/SecProtocolTypes.h If an encrypted connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ Number negotiated_tls_cipher_suite() const; /** * @brief Returns the `negotiatedTLSProtocolVersion` property of `NSURLSessionTaskTransactionMetrics`. - * @details The TLS protocol version the task negotiated with the endpoint for the connection. This value is a 2-byte sequence in host byte order. See 'tls_protocol_version_t' in 'Security/SecProtocolTypes.h' for possible values. If the task didn't negotiate an encrypted connection, this value is 'nil'. + * @details negotiatedTLSProtocolVersion is the TLS protocol version negotiated for the connection. It is a 2-byte sequence in host byte order. Please refer to tls_protocol_version_t enum in Security/SecProtocolTypes.h If an encrypted connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ Number negotiated_tls_protocol_version() const; /** * @brief Returns the `networkProtocolName` property of `NSURLSessionTaskTransactionMetrics`. - * @details The network protocol used to fetch the resource, as identified by the ALPN Protocol ID Identification Sequence [RFC7301]. E.g., h3, h2, http/1.1. When a proxy is configured AND a tunnel connection is established, then this attribute returns the value for the tunneled protocol. + * @details The network protocol used to fetch the resource, as identified by the ALPN Protocol ID Identification Sequence [RFC7301]. E.g., h3, h2, http/1.1. When a proxy is configured AND a tunnel connection is established, then this attribute returns the value for the tunneled protocol. For example: If no proxy were used, and HTTP/2 was negotiated, then h2 would be returned. If HTTP/1.1 were used to the proxy, and the tunneled connection was HTTP/2, then h2 would be returned. If HTTP/1.1 were used to the proxy, and there were no tunnel, then http/1.1 would be returned. * @return The converted Objective-C result. */ std::string network_protocol_name() const; /** * @brief Returns the `proxyConnection` property of `NSURLSessionTaskTransactionMetrics`. - * @details Whether a proxy connection was used to fetch the resource. + * @details This property is set to YES if a proxy connection was used to fetch the resource. * @return The converted Objective-C result. */ bool is_proxy_connection() const; /** * @brief Returns the `remoteAddress` property of `NSURLSessionTaskTransactionMetrics`. - * @details The IP address string of the remote interface for the connection. For multipath protocols, this is the remote address of the initial flow. If a connection was not used, this attribute is set to 'nil'. + * @details remoteAddress is the IP address string of the remote interface for the connection. For multipath protocols, this is the remote address of the initial flow. If a connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ std::string remote_address() const; /** * @brief Returns the `remotePort` property of `NSURLSessionTaskTransactionMetrics`. - * @details The port number of the remote interface for the connection. For multipath protocols, this is the remote port of the initial flow. If the app didn't use the connection, this value is 'nil'. + * @details remotePort is the port number of the remote interface for the connection. For multipath protocols, this is the remote port of the initial flow. If a connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ Number remote_port() const; @@ -187,13 +187,13 @@ namespace cocoon URLRequest request() const; /** * @brief Returns the `requestEndDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time immediately after the user agent finished requesting the source, regardless of whether the resource was retrieved from the server or local resources. + * @details requestEndDate is the time immediately after the user agent finished requesting the source, regardless of whether the resource was retrieved from the server or local resources. For example, this would correspond to the time immediately after the user agent finished sending the last byte of the request. * @return The converted Objective-C result. */ Date request_end_date() const; /** * @brief Returns the `requestStartDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time immediately before the user agent started requesting the source, regardless of whether the resource was retrieved from the server or local resources. + * @details requestStartDate is the time immediately before the user agent started requesting the source, regardless of whether the resource was retrieved from the server or local resources. For example, this would correspond to the time immediately before the user agent sent an HTTP GET request. * @return The converted Objective-C result. */ Date request_start_date() const; @@ -205,37 +205,37 @@ namespace cocoon URLSessionTaskMetricsResourceFetchType resource_fetch_type() const; /** * @brief Returns the `response` property of `NSURLSessionTaskTransactionMetrics`. - * @details Represents the transaction response. Can be 'nil' if error occurred and no response was generated. + * @details Represents the transaction response. Can be nil if error occurred and no response was generated. * @return The converted Objective-C result. */ URLResponse response() const; /** * @brief Returns the `responseEndDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time immediately after the user agent received the last byte of the resource. + * @details responseEndDate is the time immediately after the user agent received the last byte of the resource. * @return The converted Objective-C result. */ Date response_end_date() const; /** * @brief Returns the `responseStartDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details The time immediately after the user agent received the first byte of the response from the server or from local resources. + * @details responseStartDate is the time immediately after the user agent received the first byte of the response from the server or from local resources. For example, this would correspond to the time immediately after the user agent received the first byte of an HTTP response. * @return The converted Objective-C result. */ Date response_start_date() const; /** * @brief Returns the `reusedConnection` property of `NSURLSessionTaskTransactionMetrics`. - * @details Whether a persistent connection was used to fetch the resource. + * @details This property is set to YES if a persistent connection was used to fetch the resource. * @return The converted Objective-C result. */ bool is_reused_connection() const; /** * @brief Returns the `secureConnectionEndDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details If an encrypted connection was used, the time immediately after the security handshake completed. If an encrypted connection was not used, this attribute is set to 'nil'. + * @details If an encrypted connection was used, secureConnectionEndDate is the time immediately after the security handshake completed. If an encrypted connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ Date secure_connection_end_date() const; /** * @brief Returns the `secureConnectionStartDate` property of `NSURLSessionTaskTransactionMetrics`. - * @details If an encrypted connection was used, the time immediately before the user agent started the security handshake to secure the current connection. For example, this would correspond to the time immediately before the user agent started the TLS handshake. If an encrypted connection was not used, this attribute is set to 'nil'. + * @details If an encrypted connection was used, secureConnectionStartDate is the time immediately before the user agent started the security handshake to secure the current connection. For example, this would correspond to the time immediately before the user agent started the TLS handshake. If an encrypted connection was not used, this attribute is set to nil. * @return The converted Objective-C result. */ Date secure_connection_start_date() const; diff --git a/include/generated/url_session_upload_task.h b/include/generated/url_session_upload_task.h index ef426b11..edb1b692 100644 --- a/include/generated/url_session_upload_task.h +++ b/include/generated/url_session_upload_task.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSURLSessionUploadTask` (Foundation). - * @details A URL session task that uploads data to the network in a request body. The ''URLSessionUploadTask'' class is a subclass of ''URLSessionDataTask'', which in turn is a concrete subclass of ''URLSessionTask''. The methods associated with the ''URLSessionUploadTask'' class are documented in ''URLSessionTask''. Upload tasks are used for making HTTP requests that require a request body (such as 'POST' or 'PUT'). They behave similarly to data tasks, but you create them by calling different methods on the session that are designed to make it easier to provide the content to upload. As with data tasks, if the server provides a response, upload tasks return that response as one or more 'NSData' objects in memory. > Note: > Unlike data tasks, you can use upload tasks to upload content in the background. When you create an upload task, you provide a ''URLRequest'' instance that contains any additional headers that you might need to send alongside the upload, such as the content type, content disposition, and so on. In iOS, when you create an upload task for a file in a background session, the system copies that file to a temporary location and streams data from there. While the upload is in progress, the task calls the session delegate's ''URLSessionTaskDelegate/urlSession(:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:)'' method periodically to provide you with status information. When the upload phase of the request finishes, the task behaves like a data task, calling methods on the session delegate to provide you with the server's response—headers, status code, content data, and so on. + * @details An NSURLSessionUploadTask does not currently provide any additional functionality over an NSURLSessionDataTask. All delegate messages that may be sent referencing an NSURLSessionDataTask equally apply to NSURLSessionUploadTasks. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref URLSessionDataTask. * diff --git a/include/generated/url_session_web_socket_task.h b/include/generated/url_session_web_socket_task.h index 3c1b4d24..e95693c4 100644 --- a/include/generated/url_session_web_socket_task.h +++ b/include/generated/url_session_web_socket_task.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSURLSessionWebSocketTask` (Foundation). - * @details A URL session task that communicates over the WebSockets protocol standard. ''URLSessionWebSocketTask'' is a concrete subclass of ''URLSessionTask'' that provides a message-oriented transport protocol over TCP and TLS in the form of WebSocket framing. It follows the WebSocket Protocol defined in [RFC 6455](https://tools.ietf.org/html/rfc6455). You create a ''URLSessionWebSocketTask'' with either a 'ws:' or 'wss:' URL. When creating the task, you can also provide a list of protocols to advertise during the handshake phase. Once the handshake completes, your app receives notifications through the session's ''URLSession/delegate''. You send data with ''send(:completionHandler:)'' and receive data with ''receive(completionHandler:)''. The task performs reads and writes asynchronously, and allows you to send and receive messages that contain both binary frames and UTF-8 encoded text frames. The task enqueues any reads or writes you perform prior to the handshake's completion, and executes them after the handshake completes. ''URLSessionWebSocketTask'' supports redirection and authentication like other types of tasks do, using the methods in ''URLSessionTaskDelegate''. The WebSocket task calls the redirection and authentication delegate methods prior to completing the handshake. The WebSocket task also supports cookies, by storing cookies to the session configuration's ''URLSessionConfiguration/httpCookieStorage'', and attaches cookies to outgoing HTTP handshake requests. > Note: > watchOS supports ''URLSessionWebSocketTask'' for specific use cases. For more details, see \. + * @details A WebSocket task can be created with a ws or wss url. A client can also provide a list of protocols it wishes to advertise during the WebSocket handshake phase. Once the handshake is successfully completed the client will be notified through an optional delegate. All reads and writes enqueued before the completion of the handshake will be queued up and executed once the handshake succeeds. Before the handshake completes, the client can be called to handle redirection or authentication using the same delegates as NSURLSessionTask. WebSocket task will also provide support for cookies and will store cookies to the cookie storage on the session and will attach cookies to outgoing HTTP handshake requests. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref URLSessionTask. * @@ -44,51 +44,49 @@ namespace cocoon explicit URLSessionWebSocketTask(Adopt adopt); /** * @brief Calls `-[NSURLSessionWebSocketTask cancelWithCloseCode:reason:]`. - * @details Sends a close frame with the given close code. An optional reason can be provided while sending the close frame. Simply calling '-cancel' on the task will result in a cancellation frame being sent without any reason. - Parameter closeCode: The close code to send. - Parameter reason: An optional data object containing the close reason. + * @details Sends a close frame with the given closeCode. An optional reason can be provided while sending the close frame. Simply calling cancel on the task will result in a cancellation frame being sent without any reason. * @param close_code Argument converted to the Objective-C parameter of the same role. * @param reason Argument converted to the Objective-C parameter of the same role. */ void cancel_with_close_code(URLSessionWebSocketCloseCode close_code, const std::vector& reason) const; /** * @brief Calls `-[NSURLSessionWebSocketTask receiveMessageWithCompletionHandler:]`. - * @details Reads a WebSocket message once all the frames of the message are available. If the task reaches the ''maximumMessageSize'' while buffering the frames, the receive call will error out and all outstanding work will also fail, resulting in the end of the task. - Parameters: - completionHandler: A closure that receives the WebSocket message and an 'NSError' that indicates an error encountered while receiving, or 'nil' if no error occurred. + * @details Reads a WebSocket message once all the frames of the message are available. If the maximumMessage size is hit while buffering the frames, the receiveMessage call will error out and all outstanding work will also fail resulting in the end of the task. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void receive_message_with_completion_handler(std::function completion_handler) const; /** * @brief Calls `-[NSURLSessionWebSocketTask sendMessage:completionHandler:]`. - * @details Sends a WebSocket message, receiving the result in a completion handler. If an error occurs while sending the message, any outstanding work also fails. Note that invocation of the completion handler does not guarantee that the remote side has received all the bytes, only that they have been written to the kernel. - Parameters: - message: The WebSocket message to send to the other endpoint. - completionHandler: A closure that receives an 'NSError' that indicates an error encountered while sending, or 'nil' if no error occurred. + * @details Sends a WebSocket message. If an error occurs, any outstanding work will also fail. Note that invocation of the completion handler does not guarantee that the remote side has received all the bytes, only that they have been written to the kernel. * @param message Argument converted to the Objective-C parameter of the same role. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void send_message(const URLSessionWebSocketMessage& message, std::function completion_handler) const; /** * @brief Calls `-[NSURLSessionWebSocketTask sendPingWithPongReceiveHandler:]`. - * @details Sends a ping frame from the client side. The 'pongReceiveHandler' is invoked when the client receives a pong from the server endpoint. If a connection is lost or an error occurs before receiving the pong from the endpoint, the handler will be invoked with an error. The handler will always be called in the order in which the pings were sent. - Parameter pongReceiveHandler: The handler to call when a pong is received or an error occurs. + * @details Sends a ping frame from the client side. The pongReceiveHandler is invoked when the client receives a pong from the server endpoint. If a connection is lost or an error occurs before receiving the pong from the endpoint, the pongReceiveHandler block will be invoked with an error. Note - the pongReceiveHandler will always be called in the order in which the pings were sent. * @param pong_receive_handler Argument converted to the Objective-C parameter of the same role. */ void send_ping_with_pong_receive_handler(std::function pong_receive_handler) const; /** * @brief Returns the `closeCode` property of `NSURLSessionWebSocketTask`. - * @details A code that indicates the reason a connection closed. You can retrieve the close code at any time. When the task is not yet closed, this value is 'NSURLSessionWebSocketCloseCodeInvalid'. + * @details \@property NSInteger maximumMessageSize; / The maximum number of bytes to be buffered before erroring out. This includes the sum of all bytes from continuation frames. Receive calls will error out if this value is reached * @return The converted Objective-C result. */ URLSessionWebSocketCloseCode close_code() const; /** * @brief Returns the `closeReason` property of `NSURLSessionWebSocketTask`. - * @details The close reason received from the server. A task can be queried for its close reason at any point. A 'nil' value indicates no close reason or that the task is still running. + * @details \@property (readonly) NSURLSessionWebSocketCloseCode closeCode; / A task can be queried for it's close code at any point. When the task is not closed, it will be set to NSURLSessionWebSocketCloseCodeInvalid * @return The converted Objective-C result. */ std::vector close_reason() const; /** * @brief Returns the `maximumMessageSize` property of `NSURLSessionWebSocketTask`. - * @details The maximum number of bytes to be buffered before erroring out. This includes the sum of all bytes from continuation frames. Receive calls will error out if this value is reached. * @return The converted Objective-C result. */ std::int64_t maximum_message_size() const; /** * @brief Sets the `maximumMessageSize` property of `NSURLSessionWebSocketTask`. - * @details The maximum number of bytes to be buffered before erroring out. This includes the sum of all bytes from continuation frames. Receive calls will error out if this value is reached. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_maximum_message_size(std::int64_t value) const; diff --git a/include/generated/user_activity.h b/include/generated/user_activity.h index 2f5d54e9..e1db219d 100644 --- a/include/generated/user_activity.h +++ b/include/generated/user_activity.h @@ -16,7 +16,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserActivity` (Foundation). - * @details A representation of the state of your app at a moment in time. An ''NSUserActivity'' object provides a lightweight way to capture the state of your app and put it to use later. Create this object to capture information about what a person was doing, such as viewing app content, editing a document, viewing a web page, or watching a video. When the system launches your app and an activity object is available, your app can use the information in that object to restore itself to an appropriate state. Spotlight also uses these objects to improve search results for people. To allow people to continue an activity on another device, see \. \#\#\# Siri If SiriKit needs to launch your app for any reason, it creates a user activity object and assigns an appropriate \ object to its ''interaction'' property. Your app can use the interaction information to configure itself and display information related to the interaction started by SiriKit. You can also provide SiriKit with a custom user activity object containing additional data that you want passed to your app. In iOS 15 and later, a person can share content they're viewing by asking Siri to "share this". Apps built with Mac Catalyst provide the same capability with an \ in the toolbar. You can use \ or \ to provide shareable content. In iOS, if both of those properties are \, Siri uses the ''webpageURL'' property of your app's current user activity as a fallback value. \#\#\# Quick Note Quick Note on macOS and iOS can link to any app content represented as an ''NSUserActivity''. To appear as a link, the content must be the app's current activity, and provide at least one of the following identifiers: - term ''webpageURL'': An 'https:' URL, ideally in a canonical form that's consistent every time a person visits the same content. - term ''persistentIdentifier'': A string that uniquely identifies the content in this domain. The identifier should identify the same content across devices. - term ''targetContentIdentifier'': A string that uniquely identifies the content in this domain, but also allows disambiguating between multiple scenes of an app. The identifier should identify the same content across devices. To work well with Quick Note, content must adhere to the following guidelines: - The activity ''title'' should be clear and concise. This text describes the content of the link, like "Photo taken on July 27, 2020" or "Conversation with Maria". Use nouns for activity titles. - Keep the app's current activity up to date, using ''becomeCurrent()'' and ''resignCurrent()''. - Linkable identifiers (listed above) must be stable and consistent for the same content. When you link from a note to a document in an app, and later revisit that document, the system shows an indicator linking back to the note. The system compares identifiers to check that the document is the same as the original source of the link. - Maintain support for activities provided by your app, and support navigating to linked content indefinitely. Links added to notes are important to people, who may feel that a broken link indicates data loss. - Gracefully handle attempts to navigate to an activity that points to content that doesn't exist. For example, you can redirect to the new location of moved content, or show an error message. This situation may happen with shared notes, when a person links to content that exists only on another person's device. \#\#\# Search results If your ''NSUserActivity'' objects contain information that a person might want to search for later, set the ''isEligibleForSearch'' property to \. When you enable search, Spotlight indexes your user activity objects and considers them during subsequent on-device searches. For example, if a person viewed information about a particular restaurant in your app, you'd enable search for the corresponding user activity object. Subsequent searches for restaurants using Spotlight could then include the results obtained from your user activity object. In addition to on-device searches, you can contribute URLs accessed by your app with the global Spotlight search engine. Sharing a URL helps Spotlight improve its own search results for other people. To contribute a URL, put the URL in the ''webpageURL'' property of your activity object and set the ''isEligibleForPublicIndexing'' property to \. > Important: > Your app must maintain a strong reference to any activity objects that you use for search results. Employ user activity objects to record user-initiated activities, not as a general-purpose indexing mechanism of your app's data. To index all of your app's content, and not just the content touched by people, use the APIs of the \ framework. + * @details NSUserActivity encapsulates the state of a user activity in an application on a particular device, in a way that allows the same activity to be continued on another device in a corresponding application from the same developer. Examples of user user activities include editing a document, viewing a web page, or watching a video. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -60,37 +60,35 @@ namespace cocoon explicit UserActivity(Adopt adopt); /** * @brief Calls `-[NSUserActivity addUserInfoEntriesFromDictionary:]`. - * @details Adds to the user info dictionary the entries from \@c otherDictionary. The keys and values must be of the types allowed in the user info dictionary. + * @details Adds to the userInfo dictionary the entries from otherDictionary. The keys and values must be of the types allowed in the userInfo * @param other_dictionary Argument converted to the Objective-C parameter of the same role. */ void add_user_info_entries_from_dictionary(const std::vector>& other_dictionary) const; /** * @brief Calls `-[NSUserActivity becomeCurrent]`. - * @details Marks the receiver as the activity currently in use by the user. For example, the activity associated with the active window. A newly created activity is eligible for continuation on another device after the first time it becomes current. + * @details Marks the receiver as the activity currently in use by the user, for example, the activity associated with the active window. A newly created activity is eligible for continuation on another device after the first time it becomes current. */ void become_current() const; /** * @brief Calls `+[NSUserActivity deleteAllSavedUserActivitiesWithCompletionHandler:]`. - * @details Deletes all saved user activities for this application. \@param handler A completion handler that is called when the deletion is complete. * @param handler Argument converted to the Objective-C parameter of the same role. */ static void delete_all_saved_user_activities_with_completion_handler(std::function handler); /** * @brief Calls `+[NSUserActivity deleteSavedUserActivitiesWithPersistentIdentifiers:completionHandler:]`. - * @details Deletes user activities that have the specified persistent identifiers. \@param persistentIdentifiers An array of persistent identifiers for the user activities to delete. \@param handler A completion handler that is called when the deletion is complete. * @param persistent_identifiers Argument converted to the Objective-C parameter of the same role. * @param handler Argument converted to the Objective-C parameter of the same role. */ static void delete_saved_user_activities_with_persistent_identifiers(const std::vector& persistent_identifiers, std::function handler); /** * @brief Calls `-[NSUserActivity getContinuationStreamsWithCompletionHandler:]`. - * @details When an app is launched for a continuation event it can request streams back to the originating side. Streams can only be successfully retrieved from the NSUserActivity in the NS/UIApplication delegate that is called for a continuation event. The streams returned in the completion handler will be in an unopened state. The streams should be opened immediately to start requesting information from the other side. + * @details When an app is launched for a continuation event it can request streams back to the originating side. Streams can only be successfully retrieved from the NSUserActivity in the NS/UIApplication delegate that is called for a continuation event. This functionality is optional and is not expected to be needed in most continuation cases. The streams returned in the completion handler will be in an unopened state. The streams should be opened immediately to start requesting information from the other side. * @param completion_handler Argument converted to the Objective-C parameter of the same role. */ void get_continuation_streams_with_completion_handler(std::function completion_handler) const; /** * @brief Calls `-[NSUserActivity invalidate]`. - * @details Invalidate an activity when it’s no longer eligible for continuation. For example, when the window associated with an activity is closed. An invalid activity cannot become current. + * @details Invalidate an activity when it's no longer eligible for continuation, for example, when the window associated with an activity is closed. An invalid activity cannot become current. */ void invalidate() const; /** @@ -100,139 +98,137 @@ namespace cocoon void resign_current() const; /** * @brief Returns the `activityType` property of `NSUserActivity`. - * @details The activity type the user activity was created with. + * @details The activityType the user activity was created with. * @return The converted Objective-C result. */ std::string activity_type() const; /** * @brief Returns the `eligibleForHandoff` property of `NSUserActivity`. - * @details Set to \@c YES if this user activity should be eligible to be handed off to another device. + * @details Set to YES if this user activity should be eligible to be handed off to another device * @return The converted Objective-C result. */ bool is_eligible_for_handoff() const; /** * @brief Sets the `eligibleForHandoff` property of `NSUserActivity`. - * @details Set to \@c YES if this user activity should be eligible to be handed off to another device. + * @details Set to YES if this user activity should be eligible to be handed off to another device * @param value Argument converted to the Objective-C parameter of the same role. */ void set_eligible_for_handoff(bool value) const; /** * @brief Returns the `eligibleForPublicIndexing` property of `NSUserActivity`. - * @details Set to \@c YES if this user activity should be eligible for indexing for any user of this application, on any device. Set to \@c NO if the activity contains private or sensitive information or which would not be useful to other users if indexed. The activity must also have \@c requiredUserActivityKeys or a \@c webpageURL. + * @details Set to YES if this user activity should be eligible for indexing for any user of this application, on any device, or NO if the activity contains private or sensitive information or which would not be useful to other users if indexed. The activity must also have requiredUserActivityKeys or a webpageURL * @return The converted Objective-C result. */ bool is_eligible_for_public_indexing() const; /** * @brief Sets the `eligibleForPublicIndexing` property of `NSUserActivity`. - * @details Set to \@c YES if this user activity should be eligible for indexing for any user of this application, on any device. Set to \@c NO if the activity contains private or sensitive information or which would not be useful to other users if indexed. The activity must also have \@c requiredUserActivityKeys or a \@c webpageURL. + * @details Set to YES if this user activity should be eligible for indexing for any user of this application, on any device, or NO if the activity contains private or sensitive information or which would not be useful to other users if indexed. The activity must also have requiredUserActivityKeys or a webpageURL * @param value Argument converted to the Objective-C parameter of the same role. */ void set_eligible_for_public_indexing(bool value) const; /** * @brief Returns the `eligibleForSearch` property of `NSUserActivity`. - * @details Set to \@c YES if this user activity should be indexed by App History. + * @details Set to YES if this user activity should be indexed by App History * @return The converted Objective-C result. */ bool is_eligible_for_search() const; /** * @brief Sets the `eligibleForSearch` property of `NSUserActivity`. - * @details Set to \@c YES if this user activity should be indexed by App History. + * @details Set to YES if this user activity should be indexed by App History * @param value Argument converted to the Objective-C parameter of the same role. */ void set_eligible_for_search(bool value) const; /** * @brief Returns the `expirationDate` property of `NSUserActivity`. - * @details If non-nil, an absolute date after which this activity is no longer eligible to be indexed or handed off. + * @details If non-nil, then an absolute date after which this activity is no longer eligible to be indexed or handed off. * @return The converted Objective-C result. */ Date expiration_date() const; /** * @brief Sets the `expirationDate` property of `NSUserActivity`. - * @details If non-nil, an absolute date after which this activity is no longer eligible to be indexed or handed off. + * @details If non-nil, then an absolute date after which this activity is no longer eligible to be indexed or handed off. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_expiration_date(const Date& value) const; /** * @brief Returns the `keywords` property of `NSUserActivity`. - * @details A set of keywords, representing words or phrases in the current user’s language that might help the user to find this activity in the application history. + * @details A set of NSString keywords, representing words or phrases in the current user's language that might help the user to find this activity in the application history. * @return The converted Objective-C result. */ std::vector keywords() const; /** * @brief Sets the `keywords` property of `NSUserActivity`. - * @details A set of keywords, representing words or phrases in the current user’s language that might help the user to find this activity in the application history. + * @details A set of NSString keywords, representing words or phrases in the current user's language that might help the user to find this activity in the application history. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_keywords(const std::vector& value) const; /** * @brief Returns the `needsSave` property of `NSUserActivity`. - * @details If set to \@c YES, then the delegate for this user activity will receive a \@c userActivityWillSave: callback before being sent for continuation on another device. + * @details If set to YES, then the delegate for this user activity will receive a userActivityWillSave: callback before being sent for continuation on another device. * @return The converted Objective-C result. */ bool needs_save() const; /** * @brief Sets the `needsSave` property of `NSUserActivity`. - * @details If set to \@c YES, then the delegate for this user activity will receive a \@c userActivityWillSave: callback before being sent for continuation on another device. + * @details If set to YES, then the delegate for this user activity will receive a userActivityWillSave: callback before being sent for continuation on another device. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_needs_save(bool value) const; /** * @brief Returns the `persistentIdentifier` property of `NSUserActivity`. - * @details A persistent identifier for this user activity. * @return The converted Objective-C result. */ std::string persistent_identifier() const; /** * @brief Sets the `persistentIdentifier` property of `NSUserActivity`. - * @details A persistent identifier for this user activity. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_persistent_identifier(const std::string& value) const; /** * @brief Returns the `referrerURL` property of `NSUserActivity`. - * @details The URL of the webpage that referred (linked to) \@c webpageURL. + * @details The URL of the webpage that referred (linked to) webpageURL. * @return The converted Objective-C result. */ URL referrer_url() const; /** * @brief Sets the `referrerURL` property of `NSUserActivity`. - * @details The URL of the webpage that referred (linked to) \@c webpageURL. + * @details The URL of the webpage that referred (linked to) webpageURL. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_referrer_url(const URL& value) const; /** * @brief Returns the `requiredUserInfoKeys` property of `NSUserActivity`. - * @details The keys from the user info property which represent the minimal information about this user activity that should be stored for later restoration. A \@c nil value means all keys in the user info are required. + * @details The keys from the userInfo property which represent the minimal information about this user activity that should be stored for later restoration. A nil value means all keys in .userInfo are required. * @return The converted Objective-C result. */ std::vector required_user_info_keys() const; /** * @brief Sets the `requiredUserInfoKeys` property of `NSUserActivity`. - * @details The keys from the user info property which represent the minimal information about this user activity that should be stored for later restoration. A \@c nil value means all keys in the user info are required. + * @details The keys from the userInfo property which represent the minimal information about this user activity that should be stored for later restoration. A nil value means all keys in .userInfo are required. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_required_user_info_keys(const std::vector& value) const; /** * @brief Returns the `supportsContinuationStreams` property of `NSUserActivity`. - * @details When used for continuation, the user activity can allow the continuing side to connect back for more information using streams. This value is set to \@c NO by default. It can be dynamically set to \@c YES to selectively support continuation streams. + * @details When used for continuation, the user activity can allow the continuing side to connect back for more information using streams. This value is set to NO by default. It can be dynamically set to YES to selectively support continuation streams based on the state of the user activity. * @return The converted Objective-C result. */ bool supports_continuation_streams() const; /** * @brief Sets the `supportsContinuationStreams` property of `NSUserActivity`. - * @details When used for continuation, the user activity can allow the continuing side to connect back for more information using streams. This value is set to \@c NO by default. It can be dynamically set to \@c YES to selectively support continuation streams. + * @details When used for continuation, the user activity can allow the continuing side to connect back for more information using streams. This value is set to NO by default. It can be dynamically set to YES to selectively support continuation streams based on the state of the user activity. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_supports_continuation_streams(bool value) const; /** * @brief Returns the `targetContentIdentifier` property of `NSUserActivity`. - * @details A string that identifies the content of this NSUserActivity, for matching against existing documents when re-opening to see if they are the same. Setting this property is optional and does not automatically set \@c needsSave to \@c YES. + * @details A string that identifies the content of this NSUserActivity, for matching against existing documents when re-opening to see if they are the same. Setting this property is optional and does not automatically set .needsSave to YES. * @return The converted Objective-C result. */ std::string target_content_identifier() const; /** * @brief Sets the `targetContentIdentifier` property of `NSUserActivity`. - * @details A string that identifies the content of this NSUserActivity, for matching against existing documents when re-opening to see if they are the same. Setting this property is optional and does not automatically set \@c needsSave to \@c YES. + * @details A string that identifies the content of this NSUserActivity, for matching against existing documents when re-opening to see if they are the same. Setting this property is optional and does not automatically set .needsSave to YES. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_target_content_identifier(const std::string& value) const; @@ -250,25 +246,25 @@ namespace cocoon void set_title(const std::string& value) const; /** * @brief Returns the `userInfo` property of `NSUserActivity`. - * @details The user info dictionary contains application-specific state needed to continue an activity on another device. Each key and value must be of the following types: \@c NSArray, \@c NSData, \@c NSDate, \@c NSDictionary, \@c NSNull, \@c NSNumber, \@c NSSet, \@c NSString, \@c NSURL, or \@c NSUUID. + * @details The userInfo dictionary contains application-specific state needed to continue an activity on another device. Each key and value must be of the following types: NSArray, NSData, NSDate, NSDictionary, NSNull, NSNumber, NSSet, NSString, NSURL, or NSUUID. File scheme URLs which refer to iCloud documents may be translated to valid file URLs on a receiving device. * @return The converted Objective-C result. */ std::vector> user_info() const; /** * @brief Sets the `userInfo` property of `NSUserActivity`. - * @details The user info dictionary contains application-specific state needed to continue an activity on another device. Each key and value must be of the following types: \@c NSArray, \@c NSData, \@c NSDate, \@c NSDictionary, \@c NSNull, \@c NSNumber, \@c NSSet, \@c NSString, \@c NSURL, or \@c NSUUID. + * @details The userInfo dictionary contains application-specific state needed to continue an activity on another device. Each key and value must be of the following types: NSArray, NSData, NSDate, NSDictionary, NSNull, NSNumber, NSSet, NSString, NSURL, or NSUUID. File scheme URLs which refer to iCloud documents may be translated to valid file URLs on a receiving device. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_user_info(const std::vector>& value) const; /** * @brief Returns the `webpageURL` property of `NSUserActivity`. - * @details When no suitable application is installed on a resuming device and this is set, the user activity will instead be continued in a web browser by loading this resource. + * @details When no suitable application is installed on a resuming device and the webpageURL is set, the user activity will instead be continued in a web browser by loading this resource. * @return The converted Objective-C result. */ URL webpage_url() const; /** * @brief Sets the `webpageURL` property of `NSUserActivity`. - * @details When no suitable application is installed on a resuming device and this is set, the user activity will instead be continued in a web browser by loading this resource. + * @details When no suitable application is installed on a resuming device and the webpageURL is set, the user activity will instead be continued in a web browser by loading this resource. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_webpage_url(const URL& value) const; diff --git a/include/generated/user_apple_script_task.h b/include/generated/user_apple_script_task.h index 3f993839..5849f2ab 100644 --- a/include/generated/user_apple_script_task.h +++ b/include/generated/user_apple_script_task.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserAppleScriptTask` (Foundation). - * @details An object that executes AppleScript scripts. The ''NSUserAppleScriptTask'' class is intended to run AppleScript scripts from your application. It is intended to execute user-supplied scripts and will execute them outside of the application's sandbox, if any. The class is not intended to execute scripts built into an application; for that, use one of the ''Process'' classes. If the application is sandboxed, then the script must be in the ''FileManager/SearchPathDirectory/applicationScriptsDirectory'' folder. A sandboxed application may read from, but not write to, this folder. If you simply need to execute scripts without regard to input or output, use ''NSUserScriptTask'', which can execute any of the specific types. If you need specific control over the input to or output from the script, use this class. + * @details NSUserAppleScriptTask: an AppleScript script. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref UserScriptTask. * diff --git a/include/generated/user_automator_task.h b/include/generated/user_automator_task.h index fd09509e..acdceacc 100644 --- a/include/generated/user_automator_task.h +++ b/include/generated/user_automator_task.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserAutomatorTask` (Foundation). - * @details An object that executes Automator workflows. The ''NSUserAutomatorTask'' class is intended to run Automator workflows from your application. It is intended to execute user-supplied workflows, and will execute them outside of the application's sandbox, if any. The class is not intended to execute scripts built into an application; for that, use one of the ''Process'' or \ classes. If the application is sandboxed, then the script must be in the ''FileManager/SearchPathDirectory/applicationScriptsDirectory'' folder. A sandboxed application may read from, but not write to, this folder. If you simply need to execute scripts without regard to input or output, use ''NSUserScriptTask'', which can execute any of the specific types. If you need specific control over the input to or output from the workflow, use this class. + * @details NSUserAutomatorTask: an Automator workflow. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref UserScriptTask. * @@ -41,13 +41,11 @@ namespace cocoon void execute_with_input(const Object& input, std::function handler) const; /** * @brief Returns the `variables` property of `NSUserAutomatorTask`. - * @details The variables required by the Automator workflow. * @return The converted Objective-C result. */ std::map variables() const; /** * @brief Sets the `variables` property of `NSUserAutomatorTask`. - * @details The variables required by the Automator workflow. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_variables(const std::map& value) const; diff --git a/include/generated/user_defaults.h b/include/generated/user_defaults.h index 0ae1eccd..0d95d9ba 100644 --- a/include/generated/user_defaults.h +++ b/include/generated/user_defaults.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserDefaults` (Foundation). - * @details An interface to the user's defaults database, which stores system-wide and app-specific settings. A 'UserDefaults' object provides access to the defaults system, which is a persistent store for app-specific and system-wide settings. You use this system to store nonsensitive information, such as app-specific configuration details. The system also stores configuration details that apply to all apps, such as the current language settings for the device. In your code, you check values from this system and use them to dynamically alter your app's appearance or behavior. The term defaults refers to the fact that the stored data determines the default startup state and behavior. > Important: Don't store personal or sensitive information as settings. The defaults system stores information on disk in an unencrypted format. Store personal or sensitive information in the person's Keychain instead. To access the defaults system, obtain a 'UserDefaults' object and call its methods to read and write values. The ''standard'' object is a shared object you use to read and write your app's standard settings. You can also create unique 'UserDefaults' objects to manage specific sets of settings. For example, you can create a 'UserDefaults' object that reads and writes settings your app shares with an app extension. Don't subclass 'UserDefaults'. Each item you store in a defaults object consists of a key-value pair, where each key is a string that you use to locate the item and each value is a data object. The defaults database supports the same value types found in property list files, including types like 'Int', 'Float', 'Double', 'Bool', 'String', ''URL'', 'NSNumber', ''Date'', 'Array', and 'Dictionary'. To include other types of objects in the defaults database, archive them to a ''Data'' object first and store that object instead. Prefer simple types over custom objects whenever possible. With the exception of managed devices in educational institutions, the system stores defaults locally on the current device. When you write values to a 'UserDefaults' object, the object updates its in-memory version of that information right away, and writes the value to disk asynchronously. When someone backs up their device, the system includes any persistent defaults databases in the backup data. Because the data is device-specific, you don't use the defaults system to share data between devices. To share data between someone's devices, use the ''NSUbiquitousKeyValueStore'' instead. > Warning: Don't access the files of the defaults database directly from the file system. Modifying one of the underlying files directly may cause data loss, a delay in changes being available, or an app crash. In macOS, use the 'defaults' command-line utility to safely view or modify the defaults database outside of your app. While your app is running, the defaults system generates notifications to let you know when values change. To observe changes to individual settings, add a key-value observer to your 'UserDefaults' object, using key names to build the path to the setting you want. To observe changes for all settings, register for a ''didChangeNotification'' with your 'UserDefaults' object. The 'UserDefaults' type is thread-safe, and you can use the same object in multiple threads or tasks simultaneously. \#\#\# Domains and Settings Search Paths To integrate settings from different sources, the defaults system organizes them into domains. An app defines its own custom settings, but the system defines settings that apply to all apps. Similarly, you might choose to override a specific setting temporarily to test one of your app's features. The defaults system provides domains for each of these cases along with several others. When you request the value of a setting, the 'UserDefaults' object searches its domains in a specific order until it finds the value you want. The following table lists the key domains that the defaults system supports and their search order. Some domains might not be present for all apps. For example, the managed domain is present only on administrator-managed devices. | Domain | Type | Description | |----------|----------|----------| | Managed | persistent | This domain contains settings that an administrator provided for a managed device. | | Argument | volatile | This domain contains the settings you specified when launching your app from the command-line or Xcode. These keys represent temporary overrides of settings, and the system discards them after the app quits. | | Educational managed | persistent | For managed devices in an educational institution, this domain contains any settings saved to the iCloud key-value store for that institution. | | App | persistent | This domain contains the settings your app saves, either programmatically or using its settings UI. | | Suite | persistent | This domain contains custom settings from an app group or other app you specify at runtime. This domain is absent by default, but you can add a suite using the ''addSuite(named:)'' method. | | Global | persistent | This domain contains keys present for all apps on the system. The system provides the keys for this domain, and apps can't write to it. | | Registration | volatile | This domain contains system-provided default values and the default values you register for your app at launch time. Registering a set of default values prevents your code from receiving 'nil' values when requesting a setting. The system discards these values when your app quits, so you must register them each time your app launches. | The system stores data for most persistent domains on the current device, and doesn't share that data with other devices. To share settings among all of a person's devices, save them using an ''NSUbiquitousKeyValueStore'' object instead. \#\#\# Settings in Managed Environments If your app supports managed environments, an administrator might configure any managed devices with a default set of settings. Apps can't write to managed domains, so if your app encounters a managed setting, disable or hide any controls that someone might use to change that setting's value. To determine if a setting is managed, call the ''objectIsForced(forKey:)'' or ''objectIsForced(forKey:inDomain:)'' method of your 'UserDefaults' object. \#\#\# Sandbox Considerations A sandboxed app cannot access or modify the settings of another app or process, with the following exceptions: - An app can modify settings for one of its app extensions. - An app can modify settings for an app group to which it belongs. + * @details NSUserDefaults is a hierarchical persistent interprocess (optionally distributed) key-value store, optimized for storing user settings. Hierarchical: NSUserDefaults has a list of places to look for data called the "search list". A search list is referred to by an arbitrary string called the "suite identifier" or "domain identifier". When queried, NSUserDefaults checks each entry of its search list until it finds one that contains the key in question, or has searched the whole list. The list is (note: "current host + current user" preferences are unimplemented on iOS, watchOS, and tvOS, and "any user" preferences are not generally useful for applications on those operating systems): - Managed ("forced") preferences, set by a configuration profile or via mcx from a network administrator - Commandline arguments - Preferences for the current domain, in the cloud - Preferences for the current domain, the current user, in the current host - Preferences for the current domain, the current user, in any host - Preferences added via -addSuiteNamed: - Preferences global to all apps for the current user, in the current host - Preferences global to all apps for the current user, in any host - Preferences for the current domain, for all users, in the current host - Preferences global to all apps for all users, in the current host - Preferences registered with -registerDefaults: Persistent: Preferences stored in NSUserDefaults persist across reboots and relaunches of apps unless otherwise specified. Interprocess: Preferences may be accessible to and modified from multiple processes simultaneously (for example between an application and an extension). Optionally distributed (Currently only supported in Shared iPad for Students mode): Data stored in user defaults can be made "ubiqitous", i.e. synchronized between devices via the cloud. Ubiquitous user defaults are automatically propagated to all devices logged into the same iCloud account. When reading defaults (via -ForKey: methods on NSUserDefaults), ubiquitous defaults are searched before local defaults. All operations on ubiquitous defaults are asynchronous, so registered defaults may be returned in place of ubiquitous defaults if downloading from iCloud hasn't finished. Ubiquitous defaults are specified in the Defaults Configuration File for an application. Key-Value Store: NSUserDefaults stores Property List objects (NSString, NSData, NSNumber, NSDate, NSArray, and NSDictionary) identified by NSString keys, similar to an NSMutableDictionary. Optimized for storing user settings: NSUserDefaults is intended for relatively small amounts of data, queried very frequently, and modified occasionally. Using it in other ways may be slow or use more memory than solutions more suited to those uses. The 'App' CFPreferences functions in CoreFoundation act on the same search lists that NSUserDefaults does. NSUserDefaults can be observed using Key-Value Observing for any key stored in it. Using NSKeyValueObservingOptionPrior to observe changes from other processes or devices will behave as though NSKeyValueObservingOptionPrior was not specified. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -45,89 +45,87 @@ namespace cocoon explicit UserDefaults(Adopt adopt); /** * @brief Calls `-[NSUserDefaults URLForKey:]`. - * @details Returns the URL associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The URL associated with the specified key, or 'nil' if the key doesn't exist or its value can't be converted to a URL. If the value is an 'NSString' path, then it will construct a file URL to that path. If the value is an archived URL from ''UserDefaults/set(:forKey:)-2bqjt'' it will be unarchived. + * @details -URLForKey: is equivalent to -objectForKey: except that it converts the returned value to an NSURL. If the value is an NSString path, then it will construct a file URL to that path. If the value is an archived URL from -setURL:forKey: it will be unarchived. If the value is absent or can't be converted to an NSURL, nil will be returned. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ URL url_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults addSuiteNamed:]`. - * @details Inserts settings for the specified domain into the search list of the current object. - Parameter suiteName: The domain name to insert. This domain is inserted after the application domain. Passing ''NSGlobalDomain'' or the current application's bundle identifier is unsupported. The additional search lists are searched after the current domain, but before global defaults. + * @details -addSuiteNamed: adds the full search list for 'suiteName' as a sub-search-list of the receiver's. The additional search lists are searched after the current domain, but before global defaults. Passing NSGlobalDomain or the current application's bundle identifier is unsupported. * @param suite_name Argument converted to the Objective-C parameter of the same role. */ void add_suite_named(const std::string& suite_name) const; /** * @brief Calls `-[NSUserDefaults arrayForKey:]`. - * @details Returns the array associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The array associated with the specified key, or 'nil' if the key doesn't exist or its value is not an array. The returned array and its contents are immutable, even if the values you originally set were mutable. + * @details -arrayForKey: is equivalent to -objectForKey:, except that it will return nil if the value is not an NSArray. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector array_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults boolForKey:]`. - * @details Returns the Boolean value associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The Boolean value associated with the specified key. If the key doesn't exist, this method returns 'NO'. If the value is an 'NSNumber', 'NO' will be returned if the value is '0', 'YES' otherwise. If the value is an 'NSString', values of '"YES"' or '"1"' will return 'YES', and values of '"NO"', '"0"', or any other string will return 'NO'. If the value is absent or can't be converted to a 'BOOL', 'NO' will be returned. + * @details -boolForKey: is equivalent to -objectForKey:, except that it converts the returned value to a BOOL. If the value is an NSNumber, NO will be returned if the value is 0, YES otherwise. If the value is an NSString, values of "YES" or "1" will return YES, and values of "NO", "0", or any other string will return NO. If the value is absent or can't be converted to a BOOL, NO will be returned. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool bool_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults dataForKey:]`. - * @details Returns the data object associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The data object associated with the specified key, or 'nil' if the key doesn't exist or its value is not a data object. The returned data object is immutable, even if the value you originally set was mutable. + * @details -dataForKey: is equivalent to -objectForKey:, except that it will return nil if the value is not an NSData. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector data_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults dictionaryForKey:]`. - * @details Returns the dictionary object associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The dictionary object associated with the specified key, or 'nil' if the key doesn't exist or its value is not a dictionary. The returned dictionary and its contents are immutable, even if the values you originally set were mutable. + * @details -dictionaryForKey: is equivalent to -objectForKey:, except that it will return nil if the value is not an NSDictionary. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map dictionary_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults dictionaryRepresentation]`. - * @details Returns a dictionary with the union of all key-value pairs found from all domains. - Returns: A dictionary that contains the keys and their corresponding values from each of the search list's domains. For duplicate keys, the object from the domain that is closest to the front of the search list is used. + * @details -dictionaryRepresentation returns a composite snapshot of the values in the receiver's search list, such that [[receiver dictionaryRepresentation] objectForKey:x] will return the same thing as [receiver objectForKey:x]. * @return The converted Objective-C result. */ std::map dictionary_representation() const; /** * @brief Calls `-[NSUserDefaults doubleForKey:]`. - * @details Returns the double value associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The double value associated with the specified key. If the key doesn't exist, this method returns '0'. If the value is an 'NSNumber', the result of '-doubleValue' will be returned. If the value is an 'NSString', it will be converted if possible. Boolean values will not be converted. + * @details -doubleForKey: is similar to -integerForKey:, except that it returns a double, and boolean values will not be converted. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ double double_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults floatForKey:]`. - * @details Returns the floating-point value associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The float value associated with the specified key. If the key doesn't exist, this method returns '0'. If the value is an 'NSNumber', the result of '-floatValue' will be returned. If the value is an 'NSString', it will be converted if possible. Boolean values will not be converted. + * @details -floatForKey: is similar to -integerForKey:, except that it returns a float, and boolean values will not be converted. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ float float_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults integerForKey:]`. - * @details Returns the integer value associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The integer value associated with the specified key. If the key doesn't exist, this method returns '0'. If the value is an 'NSNumber', the result of '-integerValue' will be returned. If the value is an 'NSString', it will be converted to 'NSInteger' if possible. If the value is a Boolean, it will be converted to either '1' for 'YES' or '0' for 'NO'. If the value is absent or can't be converted to an integer, '0' will be returned. + * @details -integerForKey: is equivalent to -objectForKey:, except that it converts the returned value to an NSInteger. If the value is an NSNumber, the result of -integerValue will be returned. If the value is an NSString, it will be converted to NSInteger if possible. If the value is a boolean, it will be converted to either 1 for YES or 0 for NO. If the value is absent or can't be converted to an integer, 0 will be returned. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::int64_t integer_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults objectForKey:]`. - * @details Returns the object associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The object associated with the specified key, or 'nil' if the key was not found. This method searches the receiver's search list for a default with the key 'defaultName' and returns it. If another process has changed defaults in the search list, NSUserDefaults will automatically update to the latest values. If the key in question has been marked as ubiquitous via a Defaults Configuration File, the latest value may not be immediately available, and the registered value will be returned instead. The returned object is immutable, even if the value you originally set was mutable. + * @details -objectForKey: will search the receiver's search list for a default with the key 'defaultName' and return it. If another process has changed defaults in the search list, NSUserDefaults will automatically update to the latest values. If the key in question has been marked as ubiquitous via a Defaults Configuration File, the latest value may not be immediately available, and the registered value will be returned instead. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object object_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults objectIsForcedForKey:]`. - * @details Returns a Boolean value that indicates whether an administrator provided the value for the specified key. - Parameter key: The key whose status you want to check. - Returns: 'YES' if the value for 'key' is managed by an administrator; otherwise, 'NO'. A key is managed when its value has been set by a configuration profile or managed by a mobile device management (MDM) server. For keys that are managed, you should disable any user interface that allows the user to modify the value of that key. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ bool object_is_forced_for_key(const std::string& key) const; /** * @brief Calls `-[NSUserDefaults objectIsForcedForKey:inDomain:]`. - * @details Returns a Boolean value that indicates whether an administrator provided the value for the key in the specified domain. - Parameters: - key: The key whose status you want to check. - domain: The domain of the key. - Returns: 'YES' if the value for 'key' in 'domain' is managed by an administrator; otherwise, 'NO'. For keys that are managed, you should disable any user interface that allows the user to modify the value of that key. * @param key Argument converted to the Objective-C parameter of the same role. * @param domain Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -135,138 +133,135 @@ namespace cocoon bool object_is_forced_for_key(const std::string& key, const std::string& domain) const; /** * @brief Calls `-[NSUserDefaults persistentDomainForName:]`. - * @details Retrieves the settings from the specified persistent domain. - Parameter domainName: The domain name. - Returns: A dictionary containing the keys and values in the specified persistent domain, or 'nil' if the domain doesn't exist. + * @details -persistentDomainForName: returns a dictionary representation of the search list entry specified by 'domainName', the current user, and any host. * @param domain_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map persistent_domain_for_name(const std::string& domain_name) const; /** * @brief Calls `-[NSUserDefaults registerDefaults:]`. - * @details Specifies the set of default settings and values to use as a fallback in cases where the app domain doesn't have them. - Parameter registrationDictionary: The dictionary of keys and values you want to register. The contents of the registration domain are not written to disk; you need to call this method each time your application starts. You can call this method more than once; each call adds or updates the entries in the registration domain. Default values from Defaults Configuration Files will automatically be registered. + * @details -registerDefaults: adds the registrationDictionary to the last item in every search list. This means that after NSUserDefaults has looked for a value in every other valid location, it will look in registered defaults, making them useful as a "fallback" value. Registered defaults are never stored between runs of an application, and are visible only to the application that registers them. Default values from Defaults Configuration Files will automatically be registered. * @param registration_dictionary Argument converted to the Objective-C parameter of the same role. */ void register_defaults(const std::map& registration_dictionary) const; /** * @brief Calls `-[NSUserDefaults removeObjectForKey:]`. - * @details Removes the value for the specified key from the defaults database. - Parameter defaultName: The key whose value you want to remove. Removing a default has no effect on the value returned by the 'object(forKey:)' method if the same key exists in a domain that precedes the application domain in the search list. + * @details -removeObjectForKey: is equivalent to -[... setObject:nil forKey:defaultName] * @param default_name Argument converted to the Objective-C parameter of the same role. */ void remove_object_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults removePersistentDomainForName:]`. - * @details Removes the keys and values from the specified persistent domain. - Parameter domainName: The name of the persistent domain. Removes all values from the search list entry specified by 'domainName', the current user, and any host. The change is persistent. + * @details -removePersistentDomainForName: removes all values from the search list entry specified by 'domainName', the current user, and any host. The change is persistent. * @param domain_name Argument converted to the Objective-C parameter of the same role. */ void remove_persistent_domain_for_name(const std::string& domain_name) const; /** * @brief Calls `-[NSUserDefaults removeSuiteNamed:]`. - * @details Removes the specified domain from the search list of the current object. - Parameter suiteName: The domain name to remove. + * @details -removeSuiteNamed: removes a sub-searchlist added via -addSuiteNamed:. * @param suite_name Argument converted to the Objective-C parameter of the same role. */ void remove_suite_named(const std::string& suite_name) const; /** * @brief Calls `-[NSUserDefaults removeVolatileDomainForName:]`. - * @details Removes the keys and values from the specified volatile domain. - Parameter domainName: The name of the volatile domain to remove. * @param domain_name Argument converted to the Objective-C parameter of the same role. */ void remove_volatile_domain_for_name(const std::string& domain_name) const; /** * @brief Calls `+[NSUserDefaults resetStandardUserDefaults]`. - * @details This method has no effect and shouldn't be used. + * @details +resetStandardUserDefaults releases the standardUserDefaults and sets it to nil. A new standardUserDefaults will be created the next time it's accessed. The only visible effect this has is that all KVO observers of the previous standardUserDefaults will no longer be observing it. */ static void reset_standard_user_defaults(); /** * @brief Calls `-[NSUserDefaults setBool:forKey:]`. - * @details Sets the value of the specified key to a Boolean value. - Parameters: - value: The Boolean value to store. - defaultName: The key with which to associate the value. + * @details -setBool:forKey: is equivalent to -setObject:forKey: except that the value is converted from a BOOL to an NSNumber. * @param value Argument converted to the Objective-C parameter of the same role. * @param default_name Argument converted to the Objective-C parameter of the same role. */ void set_bool(bool value, const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults setDouble:forKey:]`. - * @details Sets the value of the specified key to a double. - Parameters: - value: The double value to store. - defaultName: The key with which to associate the value. + * @details -setDouble:forKey: is equivalent to -setObject:forKey: except that the value is converted from a double to an NSNumber. * @param value Argument converted to the Objective-C parameter of the same role. * @param default_name Argument converted to the Objective-C parameter of the same role. */ void set_double(double value, const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults setFloat:forKey:]`. - * @details Sets the value of the specified key to a floating-point number. - Parameters: - value: The floating-point value to store. - defaultName: The key with which to associate the value. + * @details -setFloat:forKey: is equivalent to -setObject:forKey: except that the value is converted from a float to an NSNumber. * @param value Argument converted to the Objective-C parameter of the same role. * @param default_name Argument converted to the Objective-C parameter of the same role. */ void set_float(float value, const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults setInteger:forKey:]`. - * @details Sets the value of the specified key to an integer. - Parameters: - value: The integer value to store. - defaultName: The key with which to associate the value. + * @details -setInteger:forKey: is equivalent to -setObject:forKey: except that the value is converted from an NSInteger to an NSNumber. * @param value Argument converted to the Objective-C parameter of the same role. * @param default_name Argument converted to the Objective-C parameter of the same role. */ void set_integer(std::int64_t value, const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults setObject:forKey:]`. - * @details Sets the value of the specified key to a property list object. - Parameters: - value: The object to store in the defaults database. Pass 'nil' to remove the value for 'defaultName'. - defaultName: The key with which to associate the value. This method immediately stores a value (or removes the value if 'nil' is passed) for the provided key in the search list entry for the receiver's suite name in the current user and any host, then asynchronously stores the value persistently, where it is made available to other processes. Setting a default value to a non-property-list object that can't be archived will throw an exception. + * @details -setObject:forKey: immediately stores a value (or removes the value if nil is passed as the value) for the provided key in the search list entry for the receiver's suite name in the current user and any host, then asynchronously stores the value persistently, where it is made available to other processes. * @param value Argument converted to the Objective-C parameter of the same role. * @param default_name Argument converted to the Objective-C parameter of the same role. */ void set_object(const Object& value, const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults setPersistentDomain:forName:]`. - * @details Replaces the keys and values in the specified domain with the new keys and values you supply. - Parameters: - domain: The dictionary of keys and values to assign to the domain. - domainName: The name of the persistent domain. Replaces all values in the search list entry specified by 'domainName', the current user, and any host, with the values in 'domain'. The change will be persisted. + * @details -setPersistentDomain:forName: replaces all values in the search list entry specified by 'domainName', the current user, and any host, with the values in 'domain'. The change will be persisted. * @param domain Argument converted to the Objective-C parameter of the same role. * @param domain_name Argument converted to the Objective-C parameter of the same role. */ void set_persistent_domain(const std::map& domain, const std::string& domain_name) const; /** * @brief Calls `-[NSUserDefaults setURL:forKey:]`. - * @details Sets the value of the specified key to a URL. - Parameters: - url: The URL to store. - defaultName: The key with which to associate the value. If 'url' is a file URL, the value that is archived is the 'path' with the user's home directory abbreviated using a tilde ('~') character. Use ''UserDefaults/url(forKey:)'' to retrieve values set this way. + * @details -setURL:forKey is equivalent to -setObject:forKey: except that the value is archived to an NSData. Use -URLForKey: to retrieve values set this way. * @param url Argument converted to the Objective-C parameter of the same role. * @param default_name Argument converted to the Objective-C parameter of the same role. */ void set_url(const URL& url, const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults setVolatileDomain:forName:]`. - * @details Replaces the keys and values in the specified domain with the new keys and values you supply. - Parameters: - domain: The dictionary of keys and values to assign to the domain. - domainName: The name of the volatile domain. * @param domain Argument converted to the Objective-C parameter of the same role. * @param domain_name Argument converted to the Objective-C parameter of the same role. */ void set_volatile_domain(const std::map& domain, const std::string& domain_name) const; /** * @brief Calls `-[NSUserDefaults stringArrayForKey:]`. - * @details Returns the array of strings associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The array of strings associated with the specified key, or 'nil' if the key doesn't exist, the value is not an array, or any element in the array is not a string. Unlike ''UserDefaults/string(forKey:)'', 'NSNumber' values are not converted to strings. + * @details -stringForKey: is equivalent to -objectForKey:, except that it will return nil if the value is not an NSArray\. Note that unlike -stringForKey:, NSNumbers are not converted to NSStrings. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector string_array_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults stringForKey:]`. - * @details Returns the string associated with the specified key. - Parameter defaultName: A key in the current user's defaults database. - Returns: The string associated with the specified key, or 'nil' if the key doesn't exist or the value is not a string. If the value is a number, this method converts it to a string representation. + * @details -stringForKey: is equivalent to -objectForKey:, except that it will convert NSNumber values to their NSString representation. If a non-string non-number value is found, nil will be returned. * @param default_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string string_for_key(const std::string& default_name) const; /** * @brief Calls `-[NSUserDefaults synchronize]`. - * @details Waits for any pending asynchronous updates to the defaults database and returns; this method is unnecessary and shouldn't be used. This method is unnecessary and shouldn't be used. + * @details -synchronize is deprecated and will be marked with the API_DEPRECATED macro in a future release. -synchronize blocks the calling thread until all in-progress set operations have completed. This is no longer necessary. Replacements for previous uses of -synchronize depend on what the intent of calling synchronize was. If you synchronized... - ...before reading in order to fetch updated values: remove the synchronize call - ...after writing in order to notify another program to read: the other program can use KVO to observe the default without needing to notify - ...before exiting in a non-app (command line tool, agent, or daemon) process: call CFPreferencesAppSynchronize(kCFPreferencesCurrentApplication) - ...for any other reason: remove the synchronize call * @return The converted Objective-C result. */ bool synchronize() const; /** * @brief Calls `-[NSUserDefaults volatileDomainForName:]`. - * @details Retrieves the settings from the specified volatile domain. - Parameter domainName: The name of the volatile domain. - Returns: The dictionary for the volatile domain specified by 'domainName', or 'nil' if the domain doesn't exist. * @param domain_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::map volatile_domain_for_name(const std::string& domain_name) const; /** * @brief Returns the `standardUserDefaults` property of `NSUserDefaults`. - * @details The shared defaults object for the current app. The shared defaults object searches the current application's search list, which consists of the current domain, followed by any added suite domains, the global domain, and the registration domain. + * @details +standardUserDefaults returns a global instance of NSUserDefaults configured to search the current application's search list. * @return The converted Objective-C result. */ static UserDefaults standard_user_defaults(); /** * @brief Returns the `volatileDomainNames` property of `NSUserDefaults`. - * @details An array of identifiers for the volatile domains associated with the current object. Use ''UserDefaults/volatileDomain(forName:)'' to retrieve the contents of a specific volatile domain. + * @details Volatile domains are not added to any search list, are not persisted, and are not visible to other applications. Using them is not recommended. * @return The converted Objective-C result. */ std::vector volatile_domain_names() const; diff --git a/include/generated/user_notification.h b/include/generated/user_notification.h index 7471105b..21922397 100644 --- a/include/generated/user_notification.h +++ b/include/generated/user_notification.h @@ -17,7 +17,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserNotification` (Foundation). - * @details A notification that can be scheduled for display in the notification center. \@DeprecationSummary { Use the \ framework instead. } When the system delivers a notification, information about when the notification was actually presented to the user (if at all) and other details are provided in the notification object. User applications can create ''NSUserNotification'' objects and register them with the ''NSUserNotificationCenter'' object to notify the user when an application requires attention. \#\#\# Threading Information The ''NSUserNotificationCenter'' class and the 'NSUserNotification' class are both thread safe. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -52,229 +51,191 @@ namespace cocoon explicit UserNotification(Adopt adopt); /** * @brief Returns the `actionButtonTitle` property of `NSUserNotification`. - * @details Specifies the title of the action button displayed in the notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @return The converted Objective-C result. */ std::string action_button_title() const; /** * @brief Sets the `actionButtonTitle` property of `NSUserNotification`. - * @details Specifies the title of the action button displayed in the notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_action_button_title(const std::string& value) const; /** * @brief Returns the `activationType` property of `NSUserNotification`. - * @details Specifies what caused a user notification to occur. This property specifies why the user notification was sent to the 'NSUserNotificationCenterDelegate' method 'userNotificationCenter:didActivateNotification:'. The supported values are described in 'NSUserNotificationActivationType'. * @return The converted Objective-C result. */ UserNotificationActivationType activation_type() const; /** * @brief Returns the `actualDeliveryDate` property of `NSUserNotification`. - * @details The date this notification was actually delivered. The notification center will set this value if a notification is put in the scheduled list and the delivery time arrives. If the notification is delivered directly using the 'deliverNotification:' method of the 'NSUserNotificationCenter' class, this value is set to the 'deliveryDate' value. If the 'deliveryDate' value is 'nil', this value is set to the current date. This value is used to sort the list of notifications in the user interface. * @return The converted Objective-C result. */ Date actual_delivery_date() const; /** * @brief Returns the `additionalActions` property of `NSUserNotification`. - * @details The actions that can be taken on a notification in addition to the default action. This array contains 'NSUserNotificationAction' objects that describe the different actions for a notification in addition to the default action described by 'actionButtonTitle'. * @return The converted Objective-C result. */ std::vector additional_actions() const; /** * @brief Sets the `additionalActions` property of `NSUserNotification`. - * @details The actions that can be taken on a notification in addition to the default action. This array contains 'NSUserNotificationAction' objects that describe the different actions for a notification in addition to the default action described by 'actionButtonTitle'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_additional_actions(const std::vector& value) const; /** * @brief Returns the `additionalActivationAction` property of `NSUserNotification`. - * @details An additional action selected by the user. This property specifies an additional action selected by the user when the user notification is sent to the 'NSUserNotificationCenterDelegate' method 'userNotificationCenter:didActivateNotification:'. * @return The converted Objective-C result. */ UserNotificationAction additional_activation_action() const; /** * @brief Returns the `contentImage` property of `NSUserNotification`. - * @details Image shown in the content of the notification. * @return The converted Objective-C result. */ Image content_image() const; /** * @brief Sets the `contentImage` property of `NSUserNotification`. - * @details Image shown in the content of the notification. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_content_image(const Image& value) const; /** * @brief Returns the `deliveryDate` property of `NSUserNotification`. - * @details Specifies when the notification should be delivered. The delivery date is specified in an absolute time. After a notification is delivered, it may be presented to the user. * @return The converted Objective-C result. */ Date delivery_date() const; /** * @brief Sets the `deliveryDate` property of `NSUserNotification`. - * @details Specifies when the notification should be delivered. The delivery date is specified in an absolute time. After a notification is delivered, it may be presented to the user. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_delivery_date(const Date& value) const; /** * @brief Returns the `deliveryRepeatInterval` property of `NSUserNotification`. - * @details Specifies the date components that control how often a user notification is repeated. This value may be 'nil' if the notification should not repeat. The date component values are relative to the date the notification was delivered. If the calendar value of the 'deliveryRepeatInterval' is 'nil', the current calendar is used to calculate the repeat interval. For example, if a notification should repeat every hour, set the 'hour' property of the 'deliveryRepeatInterval' to '1'. This value is ignored unless the user notification is scheduled with the 'NSUserNotificationCenter' object. * @return The converted Objective-C result. */ DateComponents delivery_repeat_interval() const; /** * @brief Sets the `deliveryRepeatInterval` property of `NSUserNotification`. - * @details Specifies the date components that control how often a user notification is repeated. This value may be 'nil' if the notification should not repeat. The date component values are relative to the date the notification was delivered. If the calendar value of the 'deliveryRepeatInterval' is 'nil', the current calendar is used to calculate the repeat interval. For example, if a notification should repeat every hour, set the 'hour' property of the 'deliveryRepeatInterval' to '1'. This value is ignored unless the user notification is scheduled with the 'NSUserNotificationCenter' object. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_delivery_repeat_interval(const DateComponents& value) const; /** * @brief Returns the `deliveryTimeZone` property of `NSUserNotification`. - * @details Specify the time zone to interpret the delivery date in. If this value is 'nil' and the user switches time zones, the notification center will adjust the time of presentation to account for the time zone change. If a notification should be delivered at a time in a specific time zone (regardless of whether the user switches time zones), set this value to the specific time zone, for example the current time zone. * @return The converted Objective-C result. */ TimeZone delivery_time_zone() const; /** * @brief Sets the `deliveryTimeZone` property of `NSUserNotification`. - * @details Specify the time zone to interpret the delivery date in. If this value is 'nil' and the user switches time zones, the notification center will adjust the time of presentation to account for the time zone change. If a notification should be delivered at a time in a specific time zone (regardless of whether the user switches time zones), set this value to the specific time zone, for example the current time zone. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_delivery_time_zone(const TimeZone& value) const; /** * @brief Returns the `hasActionButton` property of `NSUserNotification`. - * @details A Boolean value that specifies whether the notification displays an action button. Set to 'NO' if the notification has no action button. This is the case for notifications that are purely for information and have no user action. The default value is 'YES'. * @return The converted Objective-C result. */ bool has_action_button() const; /** * @brief Sets the `hasActionButton` property of `NSUserNotification`. - * @details A Boolean value that specifies whether the notification displays an action button. Set to 'NO' if the notification has no action button. This is the case for notifications that are purely for information and have no user action. The default value is 'YES'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_has_action_button(bool value) const; /** * @brief Returns the `hasReplyButton` property of `NSUserNotification`. - * @details A Boolean value that specifies whether the notification displays a reply button. Set to 'YES' if the notification has a reply button. The default value is 'NO'. If this property and 'hasActionButton' are both 'YES', the reply button is shown. * @return The converted Objective-C result. */ bool has_reply_button() const; /** * @brief Sets the `hasReplyButton` property of `NSUserNotification`. - * @details A Boolean value that specifies whether the notification displays a reply button. Set to 'YES' if the notification has a reply button. The default value is 'NO'. If this property and 'hasActionButton' are both 'YES', the reply button is shown. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_has_reply_button(bool value) const; /** * @brief Returns the `identifier` property of `NSUserNotification`. - * @details A string that uniquely identifies a notification. The identifier is unique to a notification. A notification delivered with the same identifier as an existing notification replaces the existing notification rather than causing the display of a new notification. * @return The converted Objective-C result. */ std::string identifier() const; /** * @brief Sets the `identifier` property of `NSUserNotification`. - * @details A string that uniquely identifies a notification. The identifier is unique to a notification. A notification delivered with the same identifier as an existing notification replaces the existing notification rather than causing the display of a new notification. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_identifier(const std::string& value) const; /** * @brief Returns the `informativeText` property of `NSUserNotification`. - * @details The body text of the notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @return The converted Objective-C result. */ std::string informative_text() const; /** * @brief Sets the `informativeText` property of `NSUserNotification`. - * @details The body text of the notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_informative_text(const std::string& value) const; /** * @brief Returns the `otherButtonTitle` property of `NSUserNotification`. - * @details Specifies a custom title for the close button in an alert-style notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. An empty string will cause the default localized text to be used. A 'nil' value is invalid. * @return The converted Objective-C result. */ std::string other_button_title() const; /** * @brief Sets the `otherButtonTitle` property of `NSUserNotification`. - * @details Specifies a custom title for the close button in an alert-style notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. An empty string will cause the default localized text to be used. A 'nil' value is invalid. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_other_button_title(const std::string& value) const; /** * @brief Returns the `presented` property of `NSUserNotification`. - * @details Specifies whether the user notification has been presented. In some cases, for example when your application is frontmost, the notification center may decide not to actually present a delivered notification. In that case, the value of this property is 'NO'. It is set to 'YES' if the notification was presented according to user preferences. * @return The converted Objective-C result. */ bool is_presented() const; /** * @brief Returns the `remote` property of `NSUserNotification`. - * @details Specifies whether the notification was generated by a push notification. If this property is 'YES' then the user notification was generated by a push notification (that is, remotely); if 'NO' it was generated locally. * @return The converted Objective-C result. */ bool is_remote() const; /** * @brief Returns the `response` property of `NSUserNotification`. - * @details The response with which the user responded to a notification. When the user responds to a notification, the 'NSUserNotificationCenterDelegate' method 'userNotificationCenter:didActivateNotification:' is called with the notification, the 'activationType' property set to 'NSUserNotificationActivationTypeReplied', and this property is set with the user's response. * @return The converted Objective-C result. */ AttributedString response() const; /** * @brief Returns the `responsePlaceholder` property of `NSUserNotification`. - * @details Optional placeholder string for inline reply field. * @return The converted Objective-C result. */ std::string response_placeholder() const; /** * @brief Sets the `responsePlaceholder` property of `NSUserNotification`. - * @details Optional placeholder string for inline reply field. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_response_placeholder(const std::string& value) const; /** * @brief Returns the `soundName` property of `NSUserNotification`. - * @details Specifies the name of the sound to play when the notification is delivered. Passing the 'NSUserNotificationDefaultSoundName' constant causes the default notification center sound to be played. A value of 'nil' means no sound is played. * @return The converted Objective-C result. */ std::string sound_name() const; /** * @brief Sets the `soundName` property of `NSUserNotification`. - * @details Specifies the name of the sound to play when the notification is delivered. Passing the 'NSUserNotificationDefaultSoundName' constant causes the default notification center sound to be played. A value of 'nil' means no sound is played. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_sound_name(const std::string& value) const; /** * @brief Returns the `subtitle` property of `NSUserNotification`. - * @details Specifies the subtitle of the notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @return The converted Objective-C result. */ std::string subtitle() const; /** * @brief Sets the `subtitle` property of `NSUserNotification`. - * @details Specifies the subtitle of the notification. This value should be localized as it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_subtitle(const std::string& value) const; /** * @brief Returns the `title` property of `NSUserNotification`. - * @details Specifies the title of the notification. This value should be localized because it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @return The converted Objective-C result. */ std::string title() const; /** * @brief Sets the `title` property of `NSUserNotification`. - * @details Specifies the title of the notification. This value should be localized because it is presented to the user. The string is truncated to a length appropriate for display and the property is modified to reflect the truncation. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_title(const std::string& value) const; /** * @brief Returns the `userInfo` property of `NSUserNotification`. - * @details Application-specific user info that can be attached to the notification. All items must be property list types or an exception is thrown. The 'userInfo' content must be of reasonable serialized size (less than 1KB) or an exception is thrown. * @return The converted Objective-C result. */ std::map user_info() const; /** * @brief Sets the `userInfo` property of `NSUserNotification`. - * @details Application-specific user info that can be attached to the notification. All items must be property list types or an exception is thrown. The 'userInfo' content must be of reasonable serialized size (less than 1KB) or an exception is thrown. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_user_info(const std::map& value) const; diff --git a/include/generated/user_notification_action.h b/include/generated/user_notification_action.h index 56ef839e..037e496a 100644 --- a/include/generated/user_notification_action.h +++ b/include/generated/user_notification_action.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUserNotificationAction` (Foundation). - * @details An action that the user can take in response to receiving a notification. \@DeprecationSummary { Use the \ framework instead. } User notifications can specify one or more actions to show to the user by using the ''NSUserNotification/additionalActivationAction'' or ''NSUserNotification/additionalActions'' properties. ''NSUserNotificationAction'' objects contain the localized title shown to the user and an identifier used to differentiate between presented actions. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -39,7 +38,6 @@ namespace cocoon explicit UserNotificationAction(Adopt adopt); /** * @brief Calls `+[NSUserNotificationAction actionWithIdentifier:title:]`. - * @details Creates a user notification action with a specified identifier and title. - Parameters: - identifier: The identifier for the action. - title: A localized string suitable for display to the user. * @param identifier Argument converted to the Objective-C parameter of the same role. * @param title Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -47,13 +45,11 @@ namespace cocoon static UserNotificationAction action_with_identifier(const std::string& identifier, const std::string& title); /** * @brief Returns the `identifier` property of `NSUserNotificationAction`. - * @details The identifier for the user notification action. * @return The converted Objective-C result. */ std::string identifier() const; /** * @brief Returns the `title` property of `NSUserNotificationAction`. - * @details The localized title shown to the user. * @return The converted Objective-C result. */ std::string title() const; diff --git a/include/generated/user_notification_center.h b/include/generated/user_notification_center.h index 43279021..e9ca9c8d 100644 --- a/include/generated/user_notification_center.h +++ b/include/generated/user_notification_center.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserNotificationCenter` (Foundation). - * @details An object that delivers notifications from apps to the user. \@DeprecationSummary { Use the \ framework instead. } When a user notification's delivery date has been reached, or it's manually delivered, the notification center may display the notification to the user. The user notification center reserves the right to decide if a delivered user notification is presented to the user. For example, it may suppress the notification if the application is already frontmost (the delegate can override this action). The application can check the result of this decision by examining the ''NSUserNotification/isPresented'' property of a delivered user notification. ''NSUserNotification'' instances the 'NSUserNotificationCenter' are tracking will be in one of two states: scheduled or delivered. A scheduled user notification has a ''NSUserNotification/deliveryDate''. On that delivery date, the notification will move from being scheduled to being delivered. Note that the user notification may be displayed later than the delivery date depending on many factors. A delivered user notification has an ''NSUserNotification/actualDeliveryDate''. That's the date when it moved from being scheduled to delivered, or when it was manually delivered using the ''deliver(:)'' method. The application and the user notification center are both ultimately subject to the user's preferences. If the user decides to hide all alerts from your application, the 'presented' property will still behave as above, but the user won't see any animation or hear any sound. The ''NSUserNotificationCenterDelegate'' provides more information about the delivered user notification and allows forcing the display of a user notification even if the application is frontmost. > Note: > It the user wakes more than 15 minutes after a scheduled notification is scheduled to fire, it's discarded. If the notification repeats with an interval less than 15 minutes, then it expires in 1 minute. Expired notifications are just discarded, unless they repeat, in which case, they stay in the scheduled list and just fire again later. > Important: > Many of the NSUserNotificationCenter class's methods involve talking to a server process, so calling them repeatedly can have a negative effect on performance. \#\#\# Threading Information The 'NSUserNotificationCenter' class and the ''NSUserNotification'' class are both thread safe. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -43,54 +42,45 @@ namespace cocoon explicit UserNotificationCenter(Adopt adopt); /** * @brief Calls `-[NSUserNotificationCenter deliverNotification:]`. - * @details Deliver the specified user notification. - Parameters: - notification: The user notification. The notification will be presented to the user (subject to the user's preferences). The 'presented' property of the 'NSUserNotification' object will always be set to 'YES' if a notification is delivered using this method. * @param notification Argument converted to the Objective-C parameter of the same role. */ void deliver_notification(const UserNotification& notification) const; /** * @brief Calls `-[NSUserNotificationCenter removeAllDeliveredNotifications]`. - * @details Remove all delivered user notifications from the user notification center. */ void remove_all_delivered_notifications() const; /** * @brief Calls `-[NSUserNotificationCenter removeDeliveredNotification:]`. - * @details Remove a delivered user notification from the user notification center. - Parameters: - notification: The user notification. If the user notification is not in the delivered notifications list, nothing happens. * @param notification Argument converted to the Objective-C parameter of the same role. */ void remove_delivered_notification(const UserNotification& notification) const; /** * @brief Calls `-[NSUserNotificationCenter removeScheduledNotification:]`. - * @details Removes the specified user notification from the scheduled notifications. - Parameters: - notification: The user notification. If the user notification's 'deliveryDate' occurs before the cancellation finishes, the notification may still be delivered. If the notification is not in the scheduled list, nothing happens. * @param notification Argument converted to the Objective-C parameter of the same role. */ void remove_scheduled_notification(const UserNotification& notification) const; /** * @brief Calls `-[NSUserNotificationCenter scheduleNotification:]`. - * @details Schedules the specified user notification. - Parameters: - notification: The user notification. Scheduled notifications are added to the end of the notification queue. * @param notification Argument converted to the Objective-C parameter of the same role. */ void schedule_notification(const UserNotification& notification) const; /** * @brief Returns the `defaultUserNotificationCenter` property of `NSUserNotificationCenter`. - * @details Returns the default user notification center. * @return The converted Objective-C result. */ static UserNotificationCenter default_user_notification_center(); /** * @brief Returns the `deliveredNotifications` property of `NSUserNotificationCenter`. - * @details An array of all user notifications delivered to the notification center. The number of notifications the user actually sees in the user interface may be less than the size of this array. Note that these may or may not have been actually presented to the user. See the 'presented' property in the 'NSUserNotification' class. * @return The converted Objective-C result. */ std::vector delivered_notifications() const; /** * @brief Returns the `scheduledNotifications` property of `NSUserNotificationCenter`. - * @details Specifies an array of scheduled user notifications that have not yet been delivered. Newly scheduled notifications are added to the end of the array. You may also bulk-schedule notifications by setting this array. Bulk setting new scheduled notifications unschedules existing notifications. * @return The converted Objective-C result. */ std::vector scheduled_notifications() const; /** * @brief Sets the `scheduledNotifications` property of `NSUserNotificationCenter`. - * @details Specifies an array of scheduled user notifications that have not yet been delivered. Newly scheduled notifications are added to the end of the array. You may also bulk-schedule notifications by setting this array. Bulk setting new scheduled notifications unschedules existing notifications. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_scheduled_notifications(const std::vector& value) const; diff --git a/include/generated/user_script_task.h b/include/generated/user_script_task.h index a147625c..ffb8403a 100644 --- a/include/generated/user_script_task.h +++ b/include/generated/user_script_task.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserScriptTask` (Foundation). - * @details An object that executes scripts. The ''NSUserScriptTask'' class is able to run all the scripts normally run by the one of its subclasses, however it ignores the results. It is intended to execute user-supplied scripts and will execute them outside of the application's sandbox, if any. If you need to execute scripts and get the input and output information use the ''NSUserUnixTask'', ''NSUserAppleScriptTask'', and ''NSUserAutomatorTask'' sub classes. + * @details NSUserScriptTask: An abstract "user script". * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -42,7 +42,6 @@ namespace cocoon void execute_with_completion_handler(std::function handler) const; /** * @brief Returns the `scriptURL` property of `NSUserScriptTask`. - * @details The URL of the script file. * @return The converted Objective-C result. */ URL script_url() const; diff --git a/include/generated/user_unix_task.h b/include/generated/user_unix_task.h index 9f1ec160..1a1b7235 100644 --- a/include/generated/user_unix_task.h +++ b/include/generated/user_unix_task.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSUserUnixTask` (Foundation). - * @details An object that executes unix applications. The ''NSUserUnixTask'' class is intended to run unix applications, typically a shell script, from your application. It is intended to execute user-supplied scripts, and will execute them outside of the application's sandbox, if any. The class is not intended to execute scripts built into an application; for that, use one of the ''Process'', ''NSAppleScript'', or \ classes. If the application is sandboxed, then the script must be in the ''FileManager/SearchPathDirectory/applicationScriptsDirectory'' folder. A sandboxed application may read from, but not write to, this folder. If you simply need to execute unix scripts without regard to input or output, use ''NSUserScriptTask'', which can execute any of the specific types. If you need specific control over the input to, or output from, or the error stream of the script, use this class. + * @details NSUserUnixTask: a Unix executable file, typically a shell script. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref UserScriptTask. * @@ -55,37 +55,31 @@ namespace cocoon void execute_with_arguments(const std::vector& arguments, std::function handler) const; /** * @brief Returns the `standardError` property of `NSUserUnixTask`. - * @details The standard error stream. Setting to 'nil' will bind the stream to '/dev/null'. The default is 'nil'. * @return The converted Objective-C result. */ FileHandle standard_error() const; /** * @brief Sets the `standardError` property of `NSUserUnixTask`. - * @details The standard error stream. Setting to 'nil' will bind the stream to '/dev/null'. The default is 'nil'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standard_error(const FileHandle& value) const; /** * @brief Returns the `standardInput` property of `NSUserUnixTask`. - * @details The standard input stream. Setting to 'nil' will bind the stream to '/dev/null'. The default is 'nil'. * @return The converted Objective-C result. */ FileHandle standard_input() const; /** * @brief Sets the `standardInput` property of `NSUserUnixTask`. - * @details The standard input stream. Setting to 'nil' will bind the stream to '/dev/null'. The default is 'nil'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standard_input(const FileHandle& value) const; /** * @brief Returns the `standardOutput` property of `NSUserUnixTask`. - * @details The standard output stream. Setting to 'nil' will bind the stream to '/dev/null'. The default is 'nil'. * @return The converted Objective-C result. */ FileHandle standard_output() const; /** * @brief Sets the `standardOutput` property of `NSUserUnixTask`. - * @details The standard output stream. Setting to 'nil' will bind the stream to '/dev/null'. The default is 'nil'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standard_output(const FileHandle& value) const; diff --git a/include/generated/uuid.h b/include/generated/uuid.h index a3118620..49eb1ce5 100644 --- a/include/generated/uuid.h +++ b/include/generated/uuid.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSUUID` (Foundation). - * @details A universally unique value that can be used to identify types, interfaces, and other items. In Swift, this object bridges to ''UUID''; use ''NSUUID'' when you need reference semantics or other Foundation-specific behavior. UUIDs (Universally Unique Identifiers), also known as GUIDs (Globally Unique Identifiers) or IIDs (Interface Identifiers), are 128-bit values. UUIDs created by 'NSUUID' conform to RFC 4122 version 4 and are created with random bytes. The standard format for UUIDs represented in ASCII is a string punctuated by hyphens, for example '68753A44-4D6F-1226-9C60-0050E4C00067'. The hex representation looks, as you might expect, like a list of numerical values preceded by 0x. For example, '0xD7', '0x36', '0x95', '0x0A', '0x4D', '0x6E', '0x12', '0x26', '0x80', '0x3A', '0x00', '0x50', '0xE4', '0xC0', '0x00', '0x67'. Because a UUID is expressed simply as an array of bytes, there are no endianness considerations for different platforms. The 'NSUUID' class is not toll-free bridged with CoreFoundation's \. Use UUID strings to convert between 'CFUUIDRef' and 'NSUUID', if needed. Two 'NSUUID' objects are not guaranteed to be comparable by pointer value (as \ is); use \ to compare two 'NSUUID' instances. > Important: > The Swift overlay to the Foundation framework provides the ''UUID'' structure, which bridges to the ''NSUUID'' class. For more information about value types, see \. + * @details Note: NSUUID is not toll-free bridged with CFUUID. Use UUID strings to convert between CFUUID and NSUUID, if needed. NSUUIDs are not guaranteed to be comparable by pointer value (as CFUUIDRef is); use isEqual: to compare two NSUUIDs. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -44,26 +44,26 @@ namespace cocoon explicit UUID(Adopt adopt); /** * @brief Calls `+[NSUUID UUID]`. - * @details Creates a new autoreleased NSUUID with RFC 4122 version 4 random bytes. + * @details Create a new autoreleased NSUUID with RFC 4122 version 4 random bytes * @return The converted Objective-C result. */ static UUID uuid(); /** * @brief Calls `-[NSUUID compare:]`. - * @details Compares the receiver to another NSUUID in constant time. + * @details Compare the receiver to another NSUUID in constant time * @param other_uuid Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ ComparisonResult compare(const UUID& other_uuid) const; /** * @brief Calls `-[NSUUID getUUIDBytes:]`. - * @details Gets the individual bytes of the receiver. + * @details Get the individual bytes of the receiver * @param uuid Argument converted to the Objective-C parameter of the same role. */ void get_uuid_bytes(std::uint8_t* uuid) const; /** * @brief Returns the `UUIDString` property of `NSUUID`. - * @details The UUID as a string. A string containing a formatted UUID for example 'E621E1F8-C36C-495A-93FC-0C247A3E6E5F'. + * @details Return a string description of the UUID, such as "E621E1F8-C36C-495A-93FC-0C247A3E6E5F" * @return The converted Objective-C result. */ std::string uuid_string() const; diff --git a/include/generated/value.h b/include/generated/value.h index cd468c4c..d0a2ec9e 100644 --- a/include/generated/value.h +++ b/include/generated/value.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSValue` (Foundation). - * @details A simple container for a single C or Objective-C data item. An ''NSValue'' object can hold any of the scalar types such as 'int', 'float', and 'char', as well as pointers, structures, and object 'id' references. Use this class to work with such data types in collections (such as ''NSArray'' and ''NSSet''), [Key-value coding](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/KeyValueCoding.html\#//apple_ref/doc/uid/TP40008195-CH25), and other APIs that require Objective-C objects. ''NSValue'' objects are always immutable. \#\#\# Subclassing Notes The abstract ''NSValue'' class is the public interface of a class cluster consisting mostly of private, concrete classes that create and return a value object appropriate for a given situation. It is possible to subclass ''NSValue'', but doing so requires providing storage facilities for the value (which is not inherited by subclasses) and implementing two primitive methods. \#\#\#\# Methods to Override Any subclass of ''NSValue'' must override the primitive instance methods ''getValue(:)'' and ''objCType''. These methods must operate on the storage that you provide for the value. You might want to implement an initializer for your subclass that is suited to the storage you provide. The ''NSValue'' class does not have a designated initializer, so your initializer need only invoke the \ method of 'super'. The ''NSValue'' class adopts the ''NSCopying'' and ''NSSecureCoding'' protocols; if you want instances of your own custom subclass created from copying or coding, override the methods in these protocols. You may also wish to implement the \ method to make your subclass work well in collections. \#\#\#\# Alternatives to Subclassing If you need only to use ''NSValue'' objects for wrap a custom data types or structures defined by your app, you need not create an ''NSValue'' subclass. Instead, create a category that uses existing ''NSValue'' methods to store and retrieve data of your custom type. For example, the code below defines a custom Polyhedron structure and creates ''NSValue'' convenience methods to store and retrieve it: '''objc typedef struct { int numFaces; float radius; } Polyhedron; \@interface NSValue (Polyhedron) + (instancetype)valuewithPolyhedron:(Polyhedron)value; \@property (readonly) Polyhedron polyhedronValue; \@end \@implementation NSValue (Polyhedron) + (instancetype)valuewithPolyhedron:(Polyhedron)value { return [self valueWithBytes:&value objCType:\@encode(Polyhedron)]; } - (Polyhedron) polyhedronValue { Polyhedron value; [self getValue:&value]; return value; } \@end ''' * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -57,20 +56,18 @@ namespace cocoon explicit Value(Adopt adopt); /** * @brief Calls `-[NSValue getValue:]`. - * @details Copies the value into the specified buffer. \@DeprecationSummary { This method is unsafe because it could potentially cause buffer overruns. Use ''NSValue/getValue:size:'' instead. } + * @details This method is unsafe because it could potentially cause buffer overruns. You should use -getValue:size: instead. * @param value Argument converted to the Objective-C parameter of the same role. */ void get_value(void* value) const; /** * @brief Calls `-[NSValue getValue:size:]`. - * @details Copies the value into the specified buffer. - Parameters: - value: A buffer into which to copy the value. The buffer must be large enough to hold the value. - size: The number of bytes to copy. * @param value Argument converted to the Objective-C parameter of the same role. * @param size Argument converted to the Objective-C parameter of the same role. */ void get_value(void* value, std::uint64_t size) const; /** * @brief Calls `-[NSValue isEqualToValue:]`. - * @details Returns a Boolean value that indicates whether the value object and another value object are equal. - Parameter value: The other value object with which to compare the value object. - Returns: 'YES' if both value objects are equal; otherwise, 'NO'. The ''NSValue'' class compares the type and contents of each value object to determine equality. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ @@ -87,13 +84,11 @@ namespace cocoon Insets edge_insets_value() const; /** * @brief Returns the `nonretainedObjectValue` property of `NSValue`. - * @details The value as a non-retained pointer to an object. This method is potentially dangerous, because the returned object might have been released by the time it is used. Ensure that the object has a retained reference before using it. * @return The converted Objective-C result. */ Object nonretained_object_value() const; /** * @brief Returns the `objCType` property of `NSValue`. - * @details A C string containing the Objective-C type of the data contained in the value object, as encoded by the '\@encode()' compiler directive. * @return The converted Objective-C result. */ std::string obj_c_type() const; @@ -104,7 +99,6 @@ namespace cocoon Point point_value() const; /** * @brief Returns the `pointerValue` property of `NSValue`. - * @details Returns the value as an untyped pointer. * @return The converted Objective-C result. */ void* pointer_value() const; diff --git a/include/generated/value_transformer.h b/include/generated/value_transformer.h index ccccc7fd..ce8a7978 100644 --- a/include/generated/value_transformer.h +++ b/include/generated/value_transformer.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSValueTransformer` (Foundation). - * @details An abstract class used to transform values from one representation to another. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -39,47 +38,40 @@ namespace cocoon explicit ValueTransformer(Adopt adopt); /** * @brief Calls `+[NSValueTransformer allowsReverseTransformation]`. - * @details Returns a Boolean value that indicates whether the receiver can reverse a transformation. * @return The converted Objective-C result. */ static bool allows_reverse_transformation(); /** * @brief Calls `-[NSValueTransformer reverseTransformedValue:]`. - * @details Returns the result of the reverse transformation of a given value. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object reverse_transformed_value(const Object& value) const; /** * @brief Calls `+[NSValueTransformer setValueTransformer:forName:]`. - * @details Registers the provided value transformer with a given identifier. * @param transformer Argument converted to the Objective-C parameter of the same role. * @param name Argument converted to the Objective-C parameter of the same role. */ static void set_value_transformer(const ValueTransformer& transformer, const std::string& name); /** * @brief Calls `-[NSValueTransformer transformedValue:]`. - * @details Returns the result of transforming a given value. * @param value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object transformed_value(const Object& value) const; /** * @brief Calls `+[NSValueTransformer transformedValueClass]`. - * @details Returns the class of objects returned when applying the value transformer. * @return The converted Objective-C result. */ static std::string transformed_value_class(); /** * @brief Calls `+[NSValueTransformer valueTransformerForName:]`. - * @details Returns the value transformer identified by a given identifier. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static ValueTransformer value_transformer_for_name(const std::string& name); /** * @brief Calls `+[NSValueTransformer valueTransformerNames]`. - * @details Returns an array of all the registered value transformer names. * @return The converted Objective-C result. */ static std::vector value_transformer_names(); diff --git a/include/generated/view.h b/include/generated/view.h index 21696fb0..3f138f8d 100644 --- a/include/generated/view.h +++ b/include/generated/view.h @@ -35,10 +35,7 @@ namespace cocoon class ScrollView; class Shadow; class TextInputContext; - class TextSelectionManager; class TrackingArea; - class ViewCornerConfiguration; - class ViewCornerRadii; class ViewLayoutRegion; class Window; class WritingToolsCoordinator; @@ -103,7 +100,7 @@ namespace cocoon void add_constraints(const std::vector& constraints) const; /** * @brief Calls `-[NSView addCursorRect:cursor:]`. - * @details The following methods are soft deprecated. Use the above NSTrackingArea API instead. + * @details The following methods are soft deprecated. Use the above NSTrackingArea API instead * @param rect Argument converted to the Objective-C parameter of the same role. * @param object Argument converted to the Objective-C parameter of the same role. */ @@ -135,7 +132,7 @@ namespace cocoon std::int64_t add_tool_tip_rect(const Rect& rect, const Object& owner, void* data) const; /** * @brief Calls `-[NSView addTrackingArea:]`. - * @details The following methods are meant to be invoked, and probably don't need to be overridden. + * @details The following methods are meant to be invoked, and probably don't need to be overridden * @param tracking_area Argument converted to the Objective-C parameter of the same role. */ void add_tracking_area(const TrackingArea& tracking_area) const; @@ -202,25 +199,13 @@ namespace cocoon void begin_document() const; /** * @brief Calls `-[NSView beginDraggingSessionWithItems:event:source:]`. - * @details Starts a dragging session with an array of NSDraggingItems. The frame property of each NSDraggingItem must be in the view's coordinate system. The images may animate (flock) from their initial layout into a system defined formation. Flocking may or may not be done immediately (see NSDraggingSession's flockOnBeginDrag). The visible area of the view is used as the clip rect. + * @details Starts a dragging session with a group of NSDraggingItems. The frame property of each NSDraggingItem must be in the view's coordinate system. The images may animate (flock) from thier initial layout into a system defined formation. Flocking or may not be done immediately. (see NSDraggingSession's flockOnBeginDrag. The visible area of the view is used as the clip rect. * @param items Argument converted to the Objective-C parameter of the same role. * @param event Argument converted to the Objective-C parameter of the same role. * @param source Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ DraggingSession begin_dragging_session_with_items(const std::vector& items, const Event& event, const Object& source) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSView beginDraggingSessionWithItems:gesture:source:]`. - * @details Starts a gesture based dragging session with an array of 'NSDraggingItems'. The frame property of each NSDraggingItem must be in the view's coordinate system. The images may animate (flock) from their initial layout into a system defined formation. Flocking may not be done immediately (see NSDraggingSession's flockOnBeginDrag). The visible area of the view is used as the clip rect. \@returns If the drag begins, returns the dragging session. If the drag fails to begin, returns 'nil'. - * @param items Argument converted to the Objective-C parameter of the same role. - * @param gesture Argument converted to the Objective-C parameter of the same role. - * @param source Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - DraggingSession begin_dragging_session_with_items(const std::vector& items, const GestureRecognizer& gesture, const Object& source) const; -#endif - /** * @brief Calls `-[NSView beginPageInRect:atPlacement:]`. * @param rect Argument converted to the Objective-C parameter of the same role. @@ -501,14 +486,6 @@ namespace cocoon * @return The converted Objective-C result. */ View hit_test(const Point& point) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSView invalidateCornerConfiguration]`. - * @details Invalidates the corner configuration, causing both the configuration and its dependencies to be recomputed. - */ - void invalidate_corner_configuration() const; -#endif - /** * @brief Calls `-[NSView invalidateIntrinsicContentSize]`. */ @@ -823,7 +800,7 @@ namespace cocoon void show_definition_for_attributed_string(const AttributedString& attr_string, const Point& text_baseline_origin) const; /** * @brief Calls `-[NSView showDefinitionForAttributedString:range:options:baselineOriginProvider:]`. - * @details Takes a whole attributed string with the target range (normally, this is the selected range), and shows a window displaying the definition of the specified range. The caller can pass a zero-length range and the appropriate range will be auto-detected around the range's offset. That's the recommended approach when there is no selection. This method also takes an 'options' dictionary containing options described below as key-value pairs (can be nil). Except when NSDefinitionPresentationTypeKey with NSDefinitionPresentationTypeDictionaryApplication is specified in options, the caller must supply an originProvider Block which returns the baseline origin of the first character at proposed adjustedRange in the receiver view coordinate system. If the receiver is an NSTextView, both attrString and originProvider may be nil, in which case the text view will automatically supply values suitable for displaying definitions for the specified range within its text content. This method does not cause scrolling, so clients should perform any necessary scrolling before calling this method. + * @details Takes a whole attributed string with the target range (normally, this is the selected range), and shows a window displaying the definition of the specified range. The caller can pass a zero-length range and the appropriate range will be auto-detected around the range's offset. That's the recommended approach when there is no selection. This method also an 'options' dictionary containing options described below as key-value pairs (can be nil). Except when NSDefinitionPresentationTypeKey with NSDefinitionPresentationTypeDictionaryApplication is specified in options, the caller must supply an originProvider Block which returns the baseline origin of the first character at proposed adjustedRange in the receiver view coordinate system. If the receiver is an NSTextView, both attrString and originProvider may be nil, in which case the text view will automatically supply values suitable for displaying definitions for the specified range within its text content. This method does not cause scrolling, so clients should perform any necessary scrolling before calling this method. * @param attr_string Argument converted to the Objective-C parameter of the same role. * @param target_range Argument converted to the Objective-C parameter of the same role. * @param options Argument converted to the Objective-C parameter of the same role. @@ -861,7 +838,7 @@ namespace cocoon void update_constraints_for_subtree_if_needed() const; /** * @brief Calls `-[NSView updateLayer]`. - * @details Layer Backed Views: If the view responds YES to wantsUpdateLayer, then updateLayer will be called as opposed to drawRect:. This method should be used for better performance; it is faster to directly set the layer.contents with a shared image and inform it how to stretch with the layer.contentsCenter property instead of drawing into a context with drawRect:. In general, one should also set the layerContentsRedrawPolicy to an appropriate value in the init method (frequently NSViewLayerContentsRedrawOnSetNeedsDisplay is desired). To signal a refresh of the layer contents, one will then call [view setNeedsDisplay:YES], and -updateLayer will be lazily called when the layer needs its contents. One should not alter geometry or add/remove subviews (or layers) during this method. To add subviews (or layers) use -layout. -layout will still be called even if Auto Layout is not enabled, and wantsUpdateLayer returns YES. + * @details Layer Backed Views: If the view responds YES to wantsUpdateLayer, then updateLayer will be called as opposed to drawRect:. This method should be used for better performance; it is faster to directly set the layer.contents with a shared image and inform it how to stretch with the layer.contentsCenter property instead of drawing into a context with drawRect:. In general, one should also set the layerContentsRedrawPolicy to an appropriate value in the init method (frequently NSViewLayerContentsRedrawOnSetNeedsDisplay is desired). To signal a refresh of the layer contents, one will then call [view setNeedsDisplay:YES], and -updateLayer will be lazily called when the layer needs its contents. One should not alter geometry or add/remove subviews (or layers) during this method. To add subviews (or layers) use -layout. -layout will still be called even if autolayout is not enabled, and wantsUpdateLayer returns YES. */ void update_layer() const; /** @@ -878,17 +855,9 @@ namespace cocoon * @details Override point for reacting to the effective appearance of the receiver changing. At this point 'effectiveAppearance' property reflects the new appearance. */ void view_did_change_effective_appearance() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSView viewDidChangeEffectiveCornerRadii]`. - * @details Informs the view that its effective corner radii changed. This method should be overridden to apply the corner radii to the view as required. - */ - void view_did_change_effective_corner_radii() const; -#endif - /** * @brief Calls `-[NSView viewDidEndLiveResize]`. - * @details A view receives viewDidEndLiveResize after the frame is last changed for a live resize. It is important to call [super viewDidEndLiveResize]. + * @details A view receives viewWillEndLiveResize after the frame is last changed for a live resize. It is important to call [super viewDidEndLiveResize]. */ void view_did_end_live_resize() const; /** @@ -1082,13 +1051,13 @@ namespace cocoon void set_can_draw_concurrently(bool value) const; /** * @brief Returns the `canDrawSubviewsIntoLayer` property of `NSView`. - * @details When canDrawSubviewsIntoLayer is set to YES, and the view is layer-backed (either explicitly with -wantsLayer=YES, or by having a parent view that is layer-backed), the layer will draw all subviews into this view's layer, and each subview will not get an individual layer (the exception to this is a subview which has wantsLayer explicitly set to YES). This is useful for layer-backing a complex set of views that cannot be refactored to take advantage of proper resizing and -wantsUpdateLayer==YES. If canDrawSubviewsIntoLayer is YES, the value returned from wantsUpdateLayer will be ignored, and the layer will always have drawRect: invoked to get the layer's contents. The default value is NO. NOTE: These methods should NOT be overridden, and the setter should always be used. + * @details When canDrawSubviewsIntoLayer is set to YES, and the view is layer-backed (either explicitly with -wantsLayer=YES, or by having a parent view that is layer-backed), the layer will draw all subviews into this view's layer, and each subview will not get an individual layer (the exception to this is a subview which has wantsLayer explicitly set to YES). This is useful for layer-backing a complex set of views that can not be refactored to take advantage of proper resizing and -wantsUpdateLayer==YES. If canDrawSubviewsIntoLayer is YES, the value returned from wantsUpdateLayer will be ignored, and the layer will always have drawRect: invoked to get the layer's contents. The default value is NO. NOTE: These methods should NOT be overridden, and the setter should always be used. * @return The converted Objective-C result. */ bool can_draw_subviews_into_layer() const; /** * @brief Sets the `canDrawSubviewsIntoLayer` property of `NSView`. - * @details When canDrawSubviewsIntoLayer is set to YES, and the view is layer-backed (either explicitly with -wantsLayer=YES, or by having a parent view that is layer-backed), the layer will draw all subviews into this view's layer, and each subview will not get an individual layer (the exception to this is a subview which has wantsLayer explicitly set to YES). This is useful for layer-backing a complex set of views that cannot be refactored to take advantage of proper resizing and -wantsUpdateLayer==YES. If canDrawSubviewsIntoLayer is YES, the value returned from wantsUpdateLayer will be ignored, and the layer will always have drawRect: invoked to get the layer's contents. The default value is NO. NOTE: These methods should NOT be overridden, and the setter should always be used. + * @details When canDrawSubviewsIntoLayer is set to YES, and the view is layer-backed (either explicitly with -wantsLayer=YES, or by having a parent view that is layer-backed), the layer will draw all subviews into this view's layer, and each subview will not get an individual layer (the exception to this is a subview which has wantsLayer explicitly set to YES). This is useful for layer-backing a complex set of views that can not be refactored to take advantage of proper resizing and -wantsUpdateLayer==YES. If canDrawSubviewsIntoLayer is YES, the value returned from wantsUpdateLayer will be ignored, and the layer will always have drawRect: invoked to get the layer's contents. The default value is NO. NOTE: These methods should NOT be overridden, and the setter should always be used. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_can_draw_subviews_into_layer(bool value) const; @@ -1121,7 +1090,7 @@ namespace cocoon void set_clips_to_bounds(bool value) const; /** * @brief Returns the `compatibleWithResponsiveScrolling` property of `NSView`. - * @details A subclass of any NSScrollView, NSClipView or the NSScrollView's documentView can override this method to verify that its customizations are compatible with 10.9's responsive scrolling behavior. By default, AppKit assumes that a scroll view is responsive scrolling compatible if it and its clip view and document view do not override certain methods such as -scrollWheel: (see documentation for the expanded list). However, these views may still opt into responsive scrolling if they work with the new scrolling behavior by overriding and returning YES for this method. Likewise, the same set of views may return NO to explicitly opt out of responsive scrolling. + * @details A subclass of any NSScrollView, NSClipView or the NSScrollView's documentView can override this method to verify that its customizations are compatible with 10.9's responsive scrolling behavior. By default, AppKit assumes that a ScrollView is responsive scrolling compatible if it and its clipview and document view do not override certain methods such as -scrollWheel: (See documentation for the expanded list). However, these views may still opt into responsive scrolling if they work with the new scrolling behavior by overriding and returning YES for this method. Likewise, the same set of views may return NO to explicitly opt out of responsive scrolling. * @return The converted Objective-C result. */ static bool is_compatible_with_responsive_scrolling(); @@ -1150,15 +1119,6 @@ namespace cocoon * @param value Argument converted to the Objective-C parameter of the same role. */ void set_content_filters(const std::vector& value) const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `cornerConfiguration` property of `NSView`. - * @details Defines the corner styles (e.g., square, capsule, concentric, etc) for the view’s corners. - * @return The converted Objective-C result. - */ - ViewCornerConfiguration corner_configuration() const; -#endif - /** * @brief Returns the `defaultFocusRingType` property of `NSView`. * @return The converted Objective-C result. @@ -1175,15 +1135,6 @@ namespace cocoon * @return The converted Objective-C result. */ bool is_drawing_find_indicator() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `effectiveCornerRadii` property of `NSView`. - * @details The effective radius of each corner in the view, calculated based on the corner configuration ('cornerConfiguration'). This value is 'nil' when the corner configuration is 'nil'. - * @return The converted Objective-C result. - */ - ViewCornerRadii effective_corner_radii() const; -#endif - /** * @brief Returns the `enclosingMenuItem` property of `NSView`. * @return The converted Objective-C result. @@ -1195,24 +1146,6 @@ namespace cocoon * @return The converted Objective-C result. */ ScrollView enclosing_scroll_view() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `exclusiveGestureBehavior` property of `NSView`. - * @details Declares whether gesture recognizers should be exclusive in this view and its subviews. When a view is set to '.exclusive', and one or more of its gesture recognizers is active, a second input event will not activate any further gesture recognizers, unless that event hit tests to this view or its subviews. Defaults to '.inherit'. - * @return The converted Objective-C result. - */ - ViewExclusiveGestureBehavior exclusive_gesture_behavior() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `exclusiveGestureBehavior` property of `NSView`. - * @details Declares whether gesture recognizers should be exclusive in this view and its subviews. When a view is set to '.exclusive', and one or more of its gesture recognizers is active, a second input event will not activate any further gesture recognizers, unless that event hit tests to this view or its subviews. Defaults to '.inherit'. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_exclusive_gesture_behavior(ViewExclusiveGestureBehavior value) const; -#endif - /** * @brief Returns the `firstBaselineAnchor` property of `NSView`. * @return The converted Objective-C result. @@ -1346,7 +1279,7 @@ namespace cocoon bool in_live_resize() const; /** * @brief Returns the `inputContext` property of `NSView`. - * @details Returns an 'NSTextInputContext' object for the receiver. Returns 'nil' if the receiver doesn’t conform to the 'NSTextInputClient' protocol. + * @details Returns NSTextInputContext object for the receiver. Returns nil if the receiver doesn't conform to NSTextInputClient protocol. * @return The converted Objective-C result. */ TextInputContext input_context() const; @@ -1530,13 +1463,13 @@ namespace cocoon void set_posts_frame_changed_notifications(bool value) const; /** * @brief Returns the `prefersCompactControlSizeMetrics` property of `NSView`. - * @details When this property is 'YES', any 'NSControl's in the view or its descendants will be sized with compact metrics compatible with macOS 15.0 and earlier. Defaults to 'NO'. + * @details When this property is true, any NSControls in the view or its descendants will be sized with compact metrics compatible with macOS 15 and earlier. Defaults to false * @return The converted Objective-C result. */ bool prefers_compact_control_size_metrics() const; /** * @brief Sets the `prefersCompactControlSizeMetrics` property of `NSView`. - * @details When this property is 'YES', any 'NSControl's in the view or its descendants will be sized with compact metrics compatible with macOS 15.0 and earlier. Defaults to 'NO'. + * @details When this property is true, any NSControls in the view or its descendants will be sized with compact metrics compatible with macOS 15 and earlier. Defaults to false * @param value Argument converted to the Objective-C parameter of the same role. */ void set_prefers_compact_control_size_metrics(bool value) const; @@ -1554,7 +1487,7 @@ namespace cocoon void set_prepared_content_rect(const Rect& value) const; /** * @brief Returns the `preservesContentDuringLiveResize` property of `NSView`. - * @details A view that returns YES for -preservesContentDuringLiveResize is responsible for invalidating its own dirty rects during live resize. + * @details A view that returns YES for -preservesContentDuringLiveResize is responsible for invalidating its own dirty rects during live resize * @return The converted Objective-C result. */ bool preserves_content_during_live_resize() const; @@ -1586,7 +1519,7 @@ namespace cocoon std::string print_job_title() const; /** * @brief Returns the `rectPreservedDuringLiveResize` property of `NSView`. - * @details -rectPreservedDuringLiveResize indicates the rect the view previously occupied, in the current coordinate system of the view. + * @details -rectPreservedDuringLiveResize indicates the rect the view previously occupied, in the current coordinate system of the view * @return The converted Objective-C result. */ Rect rect_preserved_during_live_resize() const; @@ -1617,13 +1550,13 @@ namespace cocoon bool is_rotated_or_scaled_from_base() const; /** * @brief Returns the `safeAreaInsets` property of `NSView`. - * @details Indicates the potentially-obscured distance from each edge of the view (e.g., not behind the window title bar, etc., if present). + * @details Indicates the potentially-obscured distance from each edge of the view (e.g, not behind the window title bar, etc., if present). * @return The converted Objective-C result. */ Insets safe_area_insets() const; /** * @brief Returns the `safeAreaLayoutGuide` property of `NSView`. - * @details This layout guide reflects the safe area for this view (i.e., the frame minus safeAreaInsets), and provides a convenient way to arrange content relative to the safe area using Auto Layout. + * @details This layout guide reflects the safe area for this view (i.e., the frame minus safeAreaInsets), and provides a convenient way to arrange content relative to the safe area using auto layout. * @return The converted Objective-C result. */ LayoutGuide safe_area_layout_guide() const; @@ -1663,22 +1596,6 @@ namespace cocoon * @return The converted Objective-C result. */ std::int64_t tag() const; -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `textSelectionManager` property of `NSView`. - * @return The converted Objective-C result. - */ - TextSelectionManager text_selection_manager() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Sets the `textSelectionManager` property of `NSView`. - * @param value Argument converted to the Objective-C parameter of the same role. - */ - void set_text_selection_manager(const TextSelectionManager& value) const; -#endif - /** * @brief Returns the `toolTip` property of `NSView`. * @return The converted Objective-C result. @@ -1761,13 +1678,13 @@ namespace cocoon void set_wants_layer(bool value) const; /** * @brief Returns the `wantsRestingTouches` property of `NSView`. - * @details In some cases, the user may rest a thumb or other touch on the device. By default, these touches are not delivered and are not included in the event's set of touches. Touches may transition in and out of resting at any time. Unless the view wants restingTouches, began / ended events are simulated as touches transition from resting to active and vice versa. + * @details In some cases, the user may rest a thumb or other touch on the device. By default, these touches are not delivered and are not included in the event's set of touches. Touches may transition in and out of resting at any time. Unless the view wants restingTouches, began / ended events are simlulated as touches transition from resting to active and vice versa. * @return The converted Objective-C result. */ bool wants_resting_touches() const; /** * @brief Sets the `wantsRestingTouches` property of `NSView`. - * @details In some cases, the user may rest a thumb or other touch on the device. By default, these touches are not delivered and are not included in the event's set of touches. Touches may transition in and out of resting at any time. Unless the view wants restingTouches, began / ended events are simulated as touches transition from resting to active and vice versa. + * @details In some cases, the user may rest a thumb or other touch on the device. By default, these touches are not delivered and are not included in the event's set of touches. Touches may transition in and out of resting at any time. Unless the view wants restingTouches, began / ended events are simlulated as touches transition from resting to active and vice versa. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_wants_resting_touches(bool value) const; diff --git a/include/generated/view_corner_configuration.h b/include/generated/view_corner_configuration.h deleted file mode 100644 index 228ef43d..00000000 --- a/include/generated/view_corner_configuration.h +++ /dev/null @@ -1,182 +0,0 @@ -#pragma once - -#include "generated/availability.h" - -#ifdef COCOON_MACOS_27 -#include "generated/enums.h" -#include "generated/structs.h" -#include "object.h" -#include "types.h" - -namespace cocoon -{ - class ViewCornerRadius; - - /** - * @brief C++ handle for the Objective-C class `NSViewCornerConfiguration` (AppKit). - * @details A configuration object that defines the corner styles of a view’s overall shape. - * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. - * - * @par Example - * @code - * #include - * - * cocoon::ViewCornerConfiguration view_corner_configuration(nullptr); // null handle; instances normally come from other API calls - * @endcode - * - * @par Common tasks - * Snippets built from this class's own members (values are placeholders). - * @code - * cocoon::ViewCornerConfiguration view_corner_configuration(nullptr); - * auto made_0 = cocoon::ViewCornerConfiguration::capsule_corner_configuration_with_maximum_radius(1); - * auto made_1 = cocoon::ViewCornerConfiguration::configuration_with_radius(cocoon::ViewCornerRadius()); - * @endcode - * @see https://developer.apple.com/documentation/appkit/nsviewcornerconfiguration - */ - class ViewCornerConfiguration : public Object - { - public: - ViewCornerConfiguration(); - /// @brief Creates a null handle that refers to no native object. - ViewCornerConfiguration(std::nullptr_t); - /// @brief Wraps an existing retained native object without creating a new one. - explicit ViewCornerConfiguration(Adopt adopt); -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration capsuleCornerConfigurationWithMaximumRadius:]`. - * @details A configuration where the container is to take on a capsule shape, scaling with the view’s size. and clamped to the 'maximumRadius'. - Parameters maximumRadius: Maximum radius for the capsule. - * @param maximum_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration capsule_corner_configuration_with_maximum_radius(double maximum_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithRadius:]`. - * @details A configuration that applies the given radius independently to all corners. When used with a container concentric radius, this allows each individual corner to resolve to different radii. - * @param radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_radius(const ViewCornerRadius& radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithTopLeftRadius:topRightRadius:bottomLeftRadius:bottomRightRadius:]`. - * @details A configuration with independent radii for each corner. - Parameters: - topLeftRadius: Radius of top left corner. - topRightRadius: Radius of top right corner. - bottomLeftRadius: Radius of bottom left corner. - bottomRightRadius: Radius of bottom right corner. - * @param top_left_radius Argument converted to the Objective-C parameter of the same role. - * @param top_right_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_left_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_right_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_top_left_radius(const ViewCornerRadius& top_left_radius, const ViewCornerRadius& top_right_radius, const ViewCornerRadius& bottom_left_radius, const ViewCornerRadius& bottom_right_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformBottomRadius:topLeftRadius:topRightRadius:]`. - * @details A configuration that applies the 'bottomRadius' uniformly to the bottom-left and bottom-right corners, with optional independent radii for the top-left and top-right corners. When the uniform corners differ, it uses the largest of the resolved corner radii. - Parameters: - bottomRadius: Radius for bottom edge. - topLeftRadius: Radius for the top left corner. - topRightRadius: Radius for the top right corner. - * @param bottom_radius Argument converted to the Objective-C parameter of the same role. - * @param top_left_radius Argument converted to the Objective-C parameter of the same role. - * @param top_right_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_bottom_radius(const ViewCornerRadius& bottom_radius, const ViewCornerRadius& top_left_radius, const ViewCornerRadius& top_right_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformLeftRadius:rightRadius:]`. - * @details A configuration that applies the 'leftRadius' uniformly to the top-left and bottom-left corners, and the 'rightRadius' uniformly to the top-right and bottom-right corners. When the uniform corners differ, it uses the largest of the resolved corner radii. - Parameters: - leftRadius: Radius for left edge. - rightRadius: Radius for the right edge. - * @param left_radius Argument converted to the Objective-C parameter of the same role. - * @param right_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_left_radius(const ViewCornerRadius& left_radius, const ViewCornerRadius& right_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformLeftRadius:topRightRadius:bottomRightRadius:]`. - * @details A configuration that applies the 'leftRadius' uniformly to the top-left and bottom-left corners, with optional independent radii for the top-right and bottom-right corners. When the uniform corners differ, it uses the largest of the resolved corner radii. - Parameters: - leftRadius: Radius for left edge. - topRightRadius: Radius for the top right corner. - bottomRightRadius: Radius for the bottom right corner. - * @param left_radius Argument converted to the Objective-C parameter of the same role. - * @param top_right_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_right_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_left_radius(const ViewCornerRadius& left_radius, const ViewCornerRadius& top_right_radius, const ViewCornerRadius& bottom_right_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformRadius:]`. - * @details A configuration that applies the given radius uniformly to all corners, using the largest of the resolved corner radii when they differ. - Parameters radius: Radius for all corners. - * @param radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_radius(const ViewCornerRadius& radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformRadius:topLeftRadius:topRightRadius:bottomLeftRadius:bottomRightRadius:]`. - * @details A configuration that applies the given uniform radius uniformly to all corners that are otherwise unspecified. Any specified corner is independent of the others. - Parameters: - radius: Uniform radius for all unspecified corners. - topLeftRadius: Radius of top left corner. - topRightRadius: Radius of top right corner. - bottomLeftRadius: Radius of bottom left corner. - bottomRightRadius: Radius of bottom right corner. - * @param radius Argument converted to the Objective-C parameter of the same role. - * @param top_left_radius Argument converted to the Objective-C parameter of the same role. - * @param top_right_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_left_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_right_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_radius(const ViewCornerRadius& radius, const ViewCornerRadius& top_left_radius, const ViewCornerRadius& top_right_radius, const ViewCornerRadius& bottom_left_radius, const ViewCornerRadius& bottom_right_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformRightRadius:topLeftRadius:bottomLeftRadius:]`. - * @details A configuration that applies the 'rightRadius' uniformly to the top-right and bottom-right corners, with optional independent radii for the top-left and bottom-left corners. When the uniform corners differ, it uses the largest of the resolved corner radii. - Parameters: - rightRadius: Radius for right edge. - topLeftRadius: Radius for the top left corner. - bottomLeftRadius: Radius for the bottom left corner. - * @param right_radius Argument converted to the Objective-C parameter of the same role. - * @param top_left_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_left_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_right_radius(const ViewCornerRadius& right_radius, const ViewCornerRadius& top_left_radius, const ViewCornerRadius& bottom_left_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformTopRadius:bottomLeftRadius:bottomRightRadius:]`. - * @details A configuration that applies the 'topRadius' uniformly to the top-left and top-right corners, with optional independent radii for the bottom-left and bottom-right corners. When the uniform corners differ, it uses the largest of the resolved corner radii. - Parameters: - topRadius: Radius for top edge. - bottomLeftRadius: Radius for the bottom left corner. - bottomRightRadius: Radius for the bottom right corner. - * @param top_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_left_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_right_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_top_radius(const ViewCornerRadius& top_radius, const ViewCornerRadius& bottom_left_radius, const ViewCornerRadius& bottom_right_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerConfiguration configurationWithUniformTopRadius:bottomRadius:]`. - * @details A configuration that applies the 'topRadius' uniformly to the top-left and top-right corners, and the 'bottomRadius' uniformly to the bottom-left and bottom-right corners. When the uniform corners differ, it uses the largest of the resolved corner radii. - Parameters: - topRadius: Radius for top edge. - bottomRadius: Radius for the bottom edge. - * @param top_radius Argument converted to the Objective-C parameter of the same role. - * @param bottom_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration configuration_with_uniform_top_radius(const ViewCornerRadius& top_radius, const ViewCornerRadius& bottom_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `capsuleCornerConfiguration` property of `NSViewCornerConfiguration`. - * @details A configuration where the container is to take on a capsule shape, scaling with the view’s size. - * @return The converted Objective-C result. - */ - static ViewCornerConfiguration capsule_corner_configuration(); -#endif - }; -} - -#endif diff --git a/include/generated/view_corner_radii.h b/include/generated/view_corner_radii.h deleted file mode 100644 index 1926b8e9..00000000 --- a/include/generated/view_corner_radii.h +++ /dev/null @@ -1,71 +0,0 @@ -#pragma once - -#include "generated/availability.h" - -#ifdef COCOON_MACOS_27 -#include "generated/enums.h" -#include "generated/structs.h" -#include "object.h" -#include "types.h" - -namespace cocoon -{ - /** - * @brief C++ handle for the Objective-C class `NSViewCornerRadii` (AppKit). - * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. - * - * @par Example - * @code - * #include - * - * cocoon::ViewCornerRadii view_corner_radii(nullptr); // null handle; instances normally come from other API calls - * @endcode - * @see https://developer.apple.com/documentation/appkit/nsviewcornerradii - */ - class ViewCornerRadii : public Object - { - public: - ViewCornerRadii(); - /// @brief Creates a null handle that refers to no native object. - ViewCornerRadii(std::nullptr_t); - /// @brief Wraps an existing retained native object without creating a new one. - explicit ViewCornerRadii(Adopt adopt); -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `bottomLeft` property of `NSViewCornerRadii`. - * @details Radius of the bottom left corner of the view. - * @return The converted Objective-C result. - */ - double bottom_left() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `bottomRight` property of `NSViewCornerRadii`. - * @details Radius of the bottom right corner of the view. - * @return The converted Objective-C result. - */ - double bottom_right() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `topLeft` property of `NSViewCornerRadii`. - * @details Radius of the top left corner of the view. - * @return The converted Objective-C result. - */ - double top_left() const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `topRight` property of `NSViewCornerRadii`. - * @details Radius of the top right corner of the view. - * @return The converted Objective-C result. - */ - double top_right() const; -#endif - }; -} - -#endif diff --git a/include/generated/view_corner_radius.h b/include/generated/view_corner_radius.h deleted file mode 100644 index ca2329b9..00000000 --- a/include/generated/view_corner_radius.h +++ /dev/null @@ -1,73 +0,0 @@ -#pragma once - -#include "generated/availability.h" - -#ifdef COCOON_MACOS_27 -#include "generated/enums.h" -#include "generated/structs.h" -#include "object.h" -#include "types.h" - -namespace cocoon -{ - /** - * @brief C++ handle for the Objective-C class `NSViewCornerRadius` (AppKit). - * @details Represents a radius used to round a corner. It supports fixed and adaptive configurations. - * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. - * - * @par Example - * @code - * #include - * - * cocoon::ViewCornerRadius view_corner_radius(nullptr); // null handle; instances normally come from other API calls - * @endcode - * - * @par Common tasks - * Snippets built from this class's own members (values are placeholders). - * @code - * cocoon::ViewCornerRadius view_corner_radius(nullptr); - * auto made_0 = cocoon::ViewCornerRadius::container_concentric_radius_with_minimum(1); - * auto made_1 = cocoon::ViewCornerRadius::fixed_radius(1); - * @endcode - * @see https://developer.apple.com/documentation/appkit/nsviewcornerradius - */ - class ViewCornerRadius : public Object - { - public: - ViewCornerRadius(); - /// @brief Creates a null handle that refers to no native object. - ViewCornerRadius(std::nullptr_t); - /// @brief Wraps an existing retained native object without creating a new one. - explicit ViewCornerRadius(Adopt adopt); -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerRadius containerConcentricRadiusWithMinimum:]`. - * @details A dynamic corner radius calculated based on the view’s container shape and limited to the provided minimum radius. - Parameter minimumRadius: Corner radius that’s applied when a corner of the view’s container is smaller than the specified radius. - * @param minimum_radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerRadius container_concentric_radius_with_minimum(double minimum_radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `+[NSViewCornerRadius fixedRadius:]`. - * @details Shorthand initializer for a configuration where all four corners are using a fixed corner radius in points. - Parameter radius: Radius for all the corners. - * @param radius Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - static ViewCornerRadius fixed_radius(double radius); -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Returns the `containerConcentricRadius` property of `NSViewCornerRadius`. - * @details A dynamic corner radius calculated based on the view’s container shape. - * @return The converted Objective-C result. - */ - static ViewCornerRadius container_concentric_radius(); -#endif - }; -} - -#endif diff --git a/include/generated/whose_specifier.h b/include/generated/whose_specifier.h index 90fb19ea..1001add5 100644 --- a/include/generated/whose_specifier.h +++ b/include/generated/whose_specifier.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSWhoseSpecifier` (Foundation). - * @details A specifier that indicates every object in a collection matching a condition. 'NSWhoseSpecifier' specifies every object in a collection (or every element in a container) that matches the condition defined by a single Boolean expression or multiple Boolean expressions connected by logical operators. 'NSWhoseSpecifier' is unique among object specifiers in that its top-level container is typically not the application object but an evaluated object specifier involved in the tested-for condition. An 'NSWhoseSpecifier' object encapsulates a "test" object for defining this condition. A test object is instantiated from a subclass of the abstract ''NSScriptWhoseTest'' class, whose one declared method is ''NSScriptWhoseTest/isTrue()''. See "Boolean Expressions and Logical Operations" in ''NSScriptObjectSpecifier'' and the descriptions in NSComparisonMethods and NSScriptingComparisonMethods for more information. The set of elements specified by an 'NSWhoseSpecifier' object can be a subset of those that pass the 'NSWhoseSpecifier' object's test. This subset is specified by the various sub-element properties of the 'NSWhoseSpecifier' object . Consider as an example the specifier 'paragraphs where color of third word is blue'. This would be represented by an 'NSWhoseSpecifier' object that uses a test specifier and another object specifier to identify a subset of the objects with the specified property. That is, the specifier's property is 'paragraphs'; the test specifier is an index specifier with property 'words' and 'index 3'; and the qualifier is a key value qualifier for key 'color' and value '[NSColor blueColor]'. The test object specifier ('word at index 3') is evaluated for each object (paragraph) using that object as the container; the resulting objects (if any) are tested with the qualifier ('color blue'). 'NSWhoseSpecifier' is part of Cocoa's built-in script handling. You don't normally subclass it. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref ScriptObjectSpecifier. * @@ -52,61 +51,51 @@ namespace cocoon explicit WhoseSpecifier(Adopt adopt); /** * @brief Returns the `endSubelementIdentifier` property of `NSWhoseSpecifier`. - * @details The identifier for the end subelement. * @return The converted Objective-C result. */ WhoseSubelementIdentifier end_subelement_identifier() const; /** * @brief Sets the `endSubelementIdentifier` property of `NSWhoseSpecifier`. - * @details The identifier for the end subelement. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_end_subelement_identifier(WhoseSubelementIdentifier value) const; /** * @brief Returns the `endSubelementIndex` property of `NSWhoseSpecifier`. - * @details The index of the end subelement. Only used if 'endSubelementIdentifier' is 'NSIndexSubelement'. * @return The converted Objective-C result. */ std::int64_t end_subelement_index() const; /** * @brief Sets the `endSubelementIndex` property of `NSWhoseSpecifier`. - * @details The index of the end subelement. Only used if 'endSubelementIdentifier' is 'NSIndexSubelement'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_end_subelement_index(std::int64_t value) const; /** * @brief Returns the `startSubelementIdentifier` property of `NSWhoseSpecifier`. - * @details The identifier for the start subelement. * @return The converted Objective-C result. */ WhoseSubelementIdentifier start_subelement_identifier() const; /** * @brief Sets the `startSubelementIdentifier` property of `NSWhoseSpecifier`. - * @details The identifier for the start subelement. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_start_subelement_identifier(WhoseSubelementIdentifier value) const; /** * @brief Returns the `startSubelementIndex` property of `NSWhoseSpecifier`. - * @details The index of the start subelement. Only used if 'startSubelementIdentifier' is 'NSIndexSubelement'. * @return The converted Objective-C result. */ std::int64_t start_subelement_index() const; /** * @brief Sets the `startSubelementIndex` property of `NSWhoseSpecifier`. - * @details The index of the start subelement. Only used if 'startSubelementIdentifier' is 'NSIndexSubelement'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_start_subelement_index(std::int64_t value) const; /** * @brief Returns the `test` property of `NSWhoseSpecifier`. - * @details The test used to qualify the objects. * @return The converted Objective-C result. */ ScriptWhoseTest test() const; /** * @brief Sets the `test` property of `NSWhoseSpecifier`. - * @details The test used to qualify the objects. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_test(const ScriptWhoseTest& value) const; diff --git a/include/generated/writing_tools_coordinator.h b/include/generated/writing_tools_coordinator.h index 7315f092..712df4ad 100644 --- a/include/generated/writing_tools_coordinator.h +++ b/include/generated/writing_tools_coordinator.h @@ -11,7 +11,6 @@ namespace cocoon class AttributedString; class UUID; class View; - class WritingToolsCoordinatorContext; /** * @brief C++ handle for the Objective-C class `NSWritingToolsCoordinator` (AppKit). @@ -52,38 +51,6 @@ namespace cocoon WritingToolsCoordinator(std::nullptr_t); /// @brief Wraps an existing retained native object without creating a new one. explicit WritingToolsCoordinator(Adopt adopt); -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSWritingToolsCoordinator cancelTextAnimationsWithIdentifiers:]`. - * @details Used to support the presentation of grammar issues in text. If it is necessary to cancel the animation of one or more issues, call this to cancel theanimations. The UUIDs passed in should be those returned when starting the animations. To cancel all ahimations, use ''stopWritingTools'' instead. - * @param identifiers Argument converted to the Objective-C parameter of the same role. - */ - void cancel_text_animations_with_identifiers(const std::vector& identifiers) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSWritingToolsCoordinator showGrammarPresentationForRange:inContext:]`. - * @details Used to support the presentation of grammar issues in text. When the user interacts with an issue, call this to bring up the relevant UI. Pass in context and range to identify the issue the user selected. The context must match one of the contexts returned from ''NSWritingToolsCoordinator/Delegate/writingToolsCoordinator(:requestsContextsFor:completion:)'' and the range must match the range in the context of one of the grammar details returned for that context from ''NSWritingToolsCoordinator/Delegate/writingToolsCoordinator(:requestsGrammarResultsFor:completion:)'' Returns NO if the UI cannot be brought up. - * @param range Argument converted to the Objective-C parameter of the same role. - * @param context Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - bool show_grammar_presentation_for_range(const Range& range, const WritingToolsCoordinatorContext& context) const; -#endif - -#ifdef COCOON_MACOS_27 - /** - * @brief Calls `-[NSWritingToolsCoordinator startTextAnimation:forRange:inContext:writingDirection:]`. - * @param text_animation Argument converted to the Objective-C parameter of the same role. - * @param range Argument converted to the Objective-C parameter of the same role. - * @param context Argument converted to the Objective-C parameter of the same role. - * @param writing_direction Argument converted to the Objective-C parameter of the same role. - * @return The converted Objective-C result. - */ - UUID start_text_animation(WritingToolsCoordinatorTextAnimation text_animation, const Range& range, const WritingToolsCoordinatorContext& context, WritingDirection writing_direction) const; -#endif - /** * @brief Calls `-[NSWritingToolsCoordinator stopWritingTools]`. * @details Stops the current Writing Tools operation and dismisses the system UI. Call this method to abort the current Writing Tools operation. This method dismisses the system’s Writing Tools UI and stops any in-flight interactions with your view. This method does not undo any changes that Writing Tools already made to your view’s content. @@ -146,7 +113,7 @@ namespace cocoon void set_includes_text_list_markers(bool value) const; /** * @brief Returns the `isWritingToolsAvailable` property of `NSWritingToolsCoordinator`. - * @details A Boolean value that indicates whether Writing Tools features are available to enable. The value of this property is 'true' when Writing Tools features are supported, even when the user has not enabled the feature. Writing Tools support might be unavailable because of device constraints. + * @details A Boolean value that indicates whether Writing Tools features are currently available. The value of this property is 'true' when Writing Tools features are available, and 'false' when they aren’t. Writing Tools support might be unavailable because of device constraints or because the system isn’t ready to process Writing Tools requests. * @return The converted Objective-C result. */ static bool is_writing_tools_available(); diff --git a/include/generated/xml_document.h b/include/generated/xml_document.h index 0b9567a9..76c52261 100644 --- a/include/generated/xml_document.h +++ b/include/generated/xml_document.h @@ -15,7 +15,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXMLDocument` (Foundation). - * @details An XML document as internalized into a logical tree structure. An ''XMLDocument'' object can have multiple child nodes but only one element, the root element. Any other node must be a ''XMLNode'' object representing a comment or a processing instruction. If you attempt to add any other kind of child node to an ''XMLDocument'' object, such as an attribute, namespace, another document object, or an element other than the root, ''XMLDocument'' raises an exception. If you add a valid child node and that object already has a parent, ''XMLDocument'' raises an exception. An ''XMLDocument'' object may also have document-global attributes, such as XML version, character encoding, referenced DTD, and MIME type. The initializers of the ''XMLDocument'' class read an external source of XML, whether it be a local file or remote website, parse it, and process it into the tree representation. You can also construct an ''XMLDocument'' programmatically. There are accessor methods for getting and setting document attributes, methods for transforming documents using XSLT, a method for dynamically validating a document, and methods for printing out the content of an ''XMLDocument'' as XML, XHTML, HTML, or plain text. The ''XMLDocument'' class is thread-safe as long as any given instance is used only in one thread. \#\#\# Subclassing Notes \#\#\#\# Methods to Override To subclass 'NSXMLDocument' you need to override the primary initializer, ''init(data:options:)'', and the methods listed below. In most cases, you need only invoke the superclass implementation, adding any subclass-specific code before or after the invocation, as necessary. - ''rootElement()'' - ''setChildren(:)'' - ''removeChild(at:)'' - ''insertChild(:at:)'' - ''characterEncoding'' - ''characterEncoding'' - ''documentContentKind'' - ''documentContentKind'' - ''dtd'' - ''mimeType'' - ''isStandalone'' - ''version'' - ''version'' By default 'NSXMLDocument' implements the 'NSObject' \ method to perform a deep comparison: two 'NSXMLDocument' objects are not considered equal unless they have the same name, same child nodes, same attributes, and so on. The comparison does not consider the parent node (and hence the node's location). If you want a different standard of comparison, override 'isEqual:'. \#\#\#\# Special Considerations Because of the architecture and data model of NSXML, when it parses and processes a source of XML it cannot know about your subclass unless you override the class method ''replacementClass(for:)'' to return your custom class in place of an 'NSXML' class. If your custom class has no direct 'NSXML' counterpart—for example, it is a subclass of 'NSXMLNode' that represents CDATA sections—then you can walk the tree after it has been created and insert the new node where appropriate. + * @details \@class NSXMLDocument \@abstract An XML Document \@discussion Note: if the application of a method would result in more than one element in the children array, an exception is thrown. Trying to add a document, namespace, attribute, or node with a parent also throws an exception. To add a node with a parent first detach or create a copy of it. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref XMLNode. * @@ -62,34 +62,34 @@ namespace cocoon explicit XMLDocument(Adopt adopt); /** * @brief Calls `-[NSXMLDocument XMLDataWithOptions:]`. - * @details Returns the XML string representation of the receiver—that is, the entire document—encapsulated in a data object. The encoding used is based on the value returned from \@c characterEncoding. \@param options One or more options (bit-OR'd if multiple) to affect the output of the document. + * @details \@method XMLDataWithOptions: \@abstract The representation of this node as it would appear in an XML document, encoded based on characterEncoding. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector xml_data_with_options(XMLNodeOptions options) const; /** * @brief Calls `-[NSXMLDocument addChild:]`. - * @details Adds a child node after the last of the receiver's existing children. \@param child The \@c NSXMLNode object to be added. + * @details \@method addChild: \@abstract Adds a child to the end of the existing children. * @param child Argument converted to the Objective-C parameter of the same role. */ void add_child(const XMLNode& child) const; /** * @brief Calls `-[NSXMLDocument insertChild:atIndex:]`. - * @details Inserts a node object at a specified position in the receiver's array of children. \@param child The \@c NSXMLNode object to be inserted. The added node must represent a comment, processing instruction, or the root element. \@param index An integer specifying the index of the children array to insert \@c child. The indexes of children after the new child are incremented. If \@c index is out of bounds, an exception is raised. + * @details \@method insertChild:atIndex: \@abstract Inserts a child at a particular index. * @param child Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_child(const XMLNode& child, std::uint64_t index) const; /** * @brief Calls `-[NSXMLDocument insertChildren:atIndex:]`. - * @details Inserts an array of children at a specified position in the receiver's array of children. \@param children An array of \@c NSXMLNode objects representing comments, processing instructions, or the root element. \@param index An integer identifying the location in the receiver's children array for insertion. If \@c index is out of bounds, an exception is raised. + * @details \@method insertChildren:atIndex: \@abstract Insert several children at a particular index. * @param children Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_children(const std::vector& children, std::uint64_t index) const; /** * @brief Calls `-[NSXMLDocument objectByApplyingXSLT:arguments:error:]`. - * @details Applies the XSLT pattern rules and templates (specified as a data object) to the receiver and returns a document object containing transformed XML or HTML markup. Depending on intended output, the method returns an \@c NSXMLDocument object or an \@c NSData object containing transformed XML or HTML markup. \@param xslt A data object containing the XSLT pattern rules and templates. \@param arguments A dictionary containing \@c NSString key-value pairs that are passed as runtime parameters to the XSLT processor. Pass in \@c nil if you have no parameters to pass. \@param error If an error occurs, indirectly returns an \@c NSError object encapsulating error or warning messages generated by XSLT processing. + * @details \@method objectByApplyingXSLT:arguments:error: \@abstract Applies XSLT with arguments (NSString key/value pairs) to this document, returning a new document. * @param xslt Argument converted to the Objective-C parameter of the same role. * @param arguments Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -97,7 +97,7 @@ namespace cocoon Object object_by_applying_xslt(const std::vector& xslt, const std::map& arguments) const; /** * @brief Calls `-[NSXMLDocument objectByApplyingXSLTAtURL:arguments:error:]`. - * @details Applies the XSLT pattern rules and templates located at a specified URL to the receiver and returns a document object containing transformed XML markup. Depending on intended output, the method returns an \@c NSXMLDocument object or an \@c NSData object containing transformed XML or HTML markup. \@param xsltURL An \@c NSURL object specifying a valid URL. \@param argument A dictionary containing \@c NSString key-value pairs that are passed as runtime parameters to the XSLT processor. Pass in \@c nil if you have no parameters to pass. \@param error If an error occurs, indirectly returns an \@c NSError object encapsulating error or warning messages generated by XSLT processing or from an attempt to connect to a website identified by the URL. + * @details \@method objectByApplyingXSLTAtURL:arguments:error: \@abstract Applies the XSLT at a URL with arguments (NSString key/value pairs) to this document, returning a new document. Error may contain a connection error from the URL. * @param xslt_url Argument converted to the Objective-C parameter of the same role. * @param argument Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -105,7 +105,7 @@ namespace cocoon Object object_by_applying_xslt_at_url(const URL& xslt_url, const std::map& argument) const; /** * @brief Calls `-[NSXMLDocument objectByApplyingXSLTString:arguments:error:]`. - * @details Applies the XSLT pattern rules and templates (specified as a string) to the receiver and returns a document object containing transformed XML or HTML markup. Depending on intended output, the method returns an \@c NSXMLDocument object or an \@c NSData object containing transformed XML or HTML markup. \@param xslt A string object containing the XSLT pattern rules and templates. \@param arguments A dictionary containing \@c NSString key-value pairs that are passed as runtime parameters to the XSLT processor. Pass in \@c nil if you have no parameters to pass. \@param error If an error occurs, indirectly returns an \@c NSError object encapsulating error or warning messages generated by XSLT processing. + * @details \@method objectByApplyingXSLTString:arguments:error: \@abstract Applies XSLT as expressed by a string with arguments (NSString key/value pairs) to this document, returning a new document. * @param xslt Argument converted to the Objective-C parameter of the same role. * @param arguments Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -113,123 +113,121 @@ namespace cocoon Object object_by_applying_xslt_string(const std::string& xslt, const std::map& arguments) const; /** * @brief Calls `-[NSXMLDocument removeChildAtIndex:]`. - * @details Removes the child node of the receiver located at a specified position in its array of children. Subsequent children have their indexes decreased by one. The removed \@c NSXMLNode object is autoreleased. \@param index An integer identifying the position of a child in the receiver's array. If \@c index is out of bounds, an exception is raised. + * @details \@method removeChildAtIndex:atIndex: \@abstract Removes a child at a particular index. * @param index Argument converted to the Objective-C parameter of the same role. */ void remove_child_at_index(std::uint64_t index) const; /** * @brief Calls `-[NSXMLDocument replaceChildAtIndex:withNode:]`. - * @details Replaces the child node of the receiver located at a specified position with another node. The removed \@c NSXMLNode object is autoreleased. \@param index An integer identifying a position in the receiver's array of children. If \@c index is out of bounds, an exception is raised. \@param node An \@c NSXMLNode object to replace the one at \@c index; it must represent a comment, a processing instruction, or the root element. + * @details \@method replaceChildAtIndex:withNode: \@abstract Replaces a child at a particular index with another child. * @param index Argument converted to the Objective-C parameter of the same role. * @param node Argument converted to the Objective-C parameter of the same role. */ void replace_child_at_index(std::uint64_t index, const XMLNode& node) const; /** * @brief Calls `+[NSXMLDocument replacementClassForClass:]`. - * @details Overridden by subclasses to substitute a custom class for an NSXML class that the parser uses to create node instances. This method is invoked before a document is parsed. The substituted class must be a subclass of \@c NSXMLNode, \@c NSXMLDocument, \@c NSXMLElement, \@c NSXMLDTD, or \@c NSXMLDTDNode. \@param cls A \@c Class object identifying an NSXML class that is to be replaced by your custom class. \@return The substituted class. * @param cls Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string replacement_class_for_class(const std::string& cls); /** * @brief Calls `-[NSXMLDocument rootElement]`. - * @details Returns the root element of the receiver. + * @details \@method rootElement \@abstract The root element. * @return The converted Objective-C result. */ XMLElement root_element() const; /** * @brief Calls `-[NSXMLDocument setChildren:]`. - * @details Sets the child nodes of the receiver. Each of these objects must represent comments, processing instructions, or the root element; otherwise, an exception is raised. Pass in \@c nil to remove all children. \@param children An array of \@c NSXMLNode objects. + * @details \@method setChildren: \@abstract Removes all existing children and replaces them with the new children. Set children to nil to simply remove all children. * @param children Argument converted to the Objective-C parameter of the same role. */ void set_children(const std::vector& children) const; /** * @brief Calls `-[NSXMLDocument setRootElement:]`. - * @details Sets the root element of the receiver. As a side effect, this method removes all other children, including \@c NSXMLNode objects representing comments and processing-instructions. \@param root An \@c NSXMLElement object that is to be the root element. + * @details \@method setRootElement: \@abstract Set the root element. Removes all other children including comments and processing-instructions. * @param root Argument converted to the Objective-C parameter of the same role. */ void set_root_element(const XMLElement& root) const; /** * @brief Calls `-[NSXMLDocument validateAndReturnError:]`. - * @details Validates the document against the governing schema and returns whether the document conforms to the schema. If the schema is defined with a DTD, this method uses the \@c NSXMLDTD object set for the receiver for validation. If the schema is based on XML Schema, the method uses the URL specified as the value of the \@c xsi:schemaLocation attribute of the root element. You can validate an XML document when it is first processed by specifying the \@c NSXMLDocumentValidate option in the initializer methods. \@param error If validation fails, on return contains an \@c NSError object describing the reason or reasons for failure. * @return The converted Objective-C result. */ bool validate_and_return_error() const; /** * @brief Returns the `DTD` property of `NSXMLDocument`. - * @details The internal DTD associated with the receiver. Returns an \@c NSXMLDTD object representing the internal DTD associated with the receiver or \@c nil if no DTD has been associated. This DTD will be output with the document. + * @details \@abstract Set the associated DTD. This DTD will be output with the document. * @return The converted Objective-C result. */ XMLDTD dtd() const; /** * @brief Sets the `DTD` property of `NSXMLDocument`. - * @details The internal DTD associated with the receiver. Returns an \@c NSXMLDTD object representing the internal DTD associated with the receiver or \@c nil if no DTD has been associated. This DTD will be output with the document. + * @details \@abstract Set the associated DTD. This DTD will be output with the document. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_dtd(const XMLDTD& value) const; /** * @brief Returns the `MIMEType` property of `NSXMLDocument`. - * @details The MIME type for the receiver (for example, "text/xml"). + * @details \@abstract Set the MIME type, eg text/xml. * @return The converted Objective-C result. */ std::string mime_type() const; /** * @brief Sets the `MIMEType` property of `NSXMLDocument`. - * @details The MIME type for the receiver (for example, "text/xml"). + * @details \@abstract Set the MIME type, eg text/xml. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_mime_type(const std::string& value) const; /** * @brief Returns the `XMLData` property of `NSXMLDocument`. - * @details The XML string representation of the receiver—that is, the entire document—encapsulated in a data object. This property invokes \@c XMLDataWithOptions: with an option of \@c NSXMLNodeOptionsNone. The encoding used is based on the value returned from \@c characterEncoding or UTF-8 if no valid encoding is returned. + * @details \@abstract Invokes XMLDataWithOptions with NSXMLNodeOptionsNone. * @return The converted Objective-C result. */ std::vector xml_data() const; /** * @brief Returns the `characterEncoding` property of `NSXMLDocument`. - * @details The character encoding of the receiver. The encoding must match the name of an IANA character set. Typically the encoding is specified in the XML declaration of a document that is processed, but it can be set at any time. If the specified encoding does not match the actual encoding, parsing of the document might fail. + * @details \@abstract Sets the character encoding to an IANA type. * @return The converted Objective-C result. */ std::string character_encoding() const; /** * @brief Sets the `characterEncoding` property of `NSXMLDocument`. - * @details The character encoding of the receiver. The encoding must match the name of an IANA character set. Typically the encoding is specified in the XML declaration of a document that is processed, but it can be set at any time. If the specified encoding does not match the actual encoding, parsing of the document might fail. + * @details \@abstract Sets the character encoding to an IANA type. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_character_encoding(const std::string& value) const; /** * @brief Returns the `documentContentKind` property of `NSXMLDocument`. - * @details The kind of output content for the receiver. Most of the differences among document-content kind have to do with the handling of content-less tags such as \@c \\\ . + * @details \@abstract The kind of document. * @return The converted Objective-C result. */ XMLDocumentContentKind document_content_kind() const; /** * @brief Sets the `documentContentKind` property of `NSXMLDocument`. - * @details The kind of output content for the receiver. Most of the differences among document-content kind have to do with the handling of content-less tags such as \@c \\\ . + * @details \@abstract The kind of document. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_document_content_kind(XMLDocumentContentKind value) const; /** * @brief Returns the `standalone` property of `NSXMLDocument`. - * @details A Boolean value that specifies whether the receiver represents a standalone XML document. A standalone document does not have an external DTD associated with it. If this option is set the standalone declaration will appear on output. + * @details \@abstract Set whether this document depends on an external DTD. If this option is set the standalone declaration will appear on output. * @return The converted Objective-C result. */ bool is_standalone() const; /** * @brief Sets the `standalone` property of `NSXMLDocument`. - * @details A Boolean value that specifies whether the receiver represents a standalone XML document. A standalone document does not have an external DTD associated with it. If this option is set the standalone declaration will appear on output. + * @details \@abstract Set whether this document depends on an external DTD. If this option is set the standalone declaration will appear on output. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_standalone(bool value) const; /** * @brief Returns the `version` property of `NSXMLDocument`. - * @details The version of the receiver's XML. Currently, the version should be either "1.0" or "1.1". + * @details \@abstract Sets the XML version. Should be 1.0 or 1.1. * @return The converted Objective-C result. */ std::string version() const; /** * @brief Sets the `version` property of `NSXMLDocument`. - * @details The version of the receiver's XML. Currently, the version should be either "1.0" or "1.1". + * @details \@abstract Sets the XML version. Should be 1.0 or 1.1. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_version(const std::string& value) const; diff --git a/include/generated/xml_element.h b/include/generated/xml_element.h index 069643c1..f1ea9a03 100644 --- a/include/generated/xml_element.h +++ b/include/generated/xml_element.h @@ -12,7 +12,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXMLElement` (Foundation). - * @details The element nodes in an XML tree structure. An ''XMLElement'' object may have child nodes, specifically comment nodes, processing-instruction nodes, text nodes, and other ''XMLElement'' nodes. It may also have attribute nodes and namespace nodes associated with it (however, namespace and attribute nodes are not considered children). Any attempt to add a ''XMLDocument'' node, ''XMLDTD'' node, namespace node, or attribute node as a child raises an exception. If you add a child node to an ''XMLElement'' object and that child already has a parent, ''XMLElement'' raises an exception; the child must be detached or copied first. \#\#\# Subclassing Notes You can subclass 'NSXMLElement' if you want element nodes with more specialized attributes or behavior, for example, paragraph and font attributes that specify how the string value of the element should appear. \#\#\#\# Methods to Override To subclass 'NSXMLElement' you need to override the primary initializer, ''init(name:uri:)'', and the methods listed below. In most cases, you need only invoke the superclass implementation, adding any subclass-specific code before or after the invocation, as necessary. | ''addAttribute(:)'' | ''removeNamespace(forPrefix:)'' | |---|---| | ''removeAttribute(forName:)'' | ''namespaces'' | | ''attributes'' | ''namespaces'' | | ''attribute(forLocalName:uri:)'' | ''insertChild(:at:)'' | | ''attributes'' | ''removeChild(at:)'' | | ''addNamespace(:)'' | ''setChildren(:)'' | 'NSXMLElement' implements \ to perform a deep comparison: two ''XMLDocument'' objects are not considered equal unless they have the same name, same child nodes, same attributes, and so on. If you want a different standard of comparison, override 'isEqual:'. \#\#\#\# Special Considerations Because of the architecture and data model of NSXML, when it parses and processes a source of XML it cannot know about your subclass unless you override the class method ''XMLDocument/replacementClass(for:)'' to return your custom class in place of an NSXML class. If your custom class has no direct NSXML counterpart—for example, it is a subclass of 'NSXMLNode' that represents CDATA sections—then you can walk the tree after it has been created and insert the new node where appropriate. Note that you can safely set the root element of the XML document (using the 'NSXMLDocument' ''XMLDocument/setRootElement(:)''method) to be an instance of your subclass because this method only checks to see if the added node is of an element kind ('NSXMLElementKind'). These precautions do not apply, of course, if you are creating an XML tree programmatically. + * @details \@class NSXMLElement \@abstract An XML element \@discussion Note: Trying to add a document, namespace, attribute, or node with a parent throws an exception. To add a node with a parent first detach or create a copy of it. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref XMLNode. * @@ -50,25 +50,25 @@ namespace cocoon explicit XMLElement(Adopt adopt); /** * @brief Calls `-[NSXMLElement addAttribute:]`. - * @details Adds an attribute node to the receiver. If the receiver already has an attribute with the same name, \@c attribute replaces the old attribute. The order of multiple attributes is preserved if the \@c NSXMLPreserveAttributeOrder option is specified when the element is created. \@param attribute An XML node object representing an attribute. + * @details \@method addAttribute: \@abstract Adds an attribute. Attributes with duplicate names are not added. * @param attribute Argument converted to the Objective-C parameter of the same role. */ void add_attribute(const XMLNode& attribute) const; /** * @brief Calls `-[NSXMLElement addChild:]`. - * @details Adds a child node at the end of the receiver's current list of children. The new node has an index value that is one greater than the last of the current children. \@param child An XML node object to add to the receiver's children. + * @details \@method addChild: \@abstract Adds a child to the end of the existing children. * @param child Argument converted to the Objective-C parameter of the same role. */ void add_child(const XMLNode& child) const; /** * @brief Calls `-[NSXMLElement addNamespace:]`. - * @details Adds a namespace node to the receiver. If the receiver already has a namespace with the same name, \@c aNamespace is not added. \@param aNamespace An XML node object of kind \@c NSXMLNamespaceKind. + * @details \@method addNamespace:URI: \@abstract Adds a namespace. Namespaces with duplicate names are not added. * @param a_namespace Argument converted to the Objective-C parameter of the same role. */ void add_namespace(const XMLNode& a_namespace) const; /** * @brief Calls `-[NSXMLElement attributeForLocalName:URI:]`. - * @details Returns the attribute node of the receiver that is identified by a local name and URI. \@param localName A string specifying the local name of an attribute. \@param URI A string identifying the URI associated with an attribute. \@return An XML node object representing a matching attribute or \@c nil if no such node was found. + * @details \@method attributeForLocalName:URI: \@abstract Returns an attribute matching this localname URI pair. * @param local_name Argument converted to the Objective-C parameter of the same role. * @param uri Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -76,14 +76,14 @@ namespace cocoon XMLNode attribute_for_local_name(const std::string& local_name, const std::string& uri) const; /** * @brief Calls `-[NSXMLElement attributeForName:]`. - * @details Returns the attribute node of the receiver with the specified name. If \@c name is a qualified name, then this method invokes \@c attributeForLocalName:URI: with the URI parameter set to the URI associated with the prefix. Otherwise comparison is based on string equality of the qualified or non-qualified name. \@param name A string specifying the name of an attribute. \@return An XML node object representing a matching attribute or \@c nil if no such node was found. + * @details \@method attributeForName: \@abstract Returns an attribute matching this name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ XMLNode attribute_for_name(const std::string& name) const; /** * @brief Calls `-[NSXMLElement elementsForLocalName:URI:]`. - * @details Returns the child element nodes (as \@c NSXMLElement objects) of the receiver that are matched with the specified local name and URI. \@param localName A string specifying a local name of an element. \@param URI A string specifying a URI associated with an element. \@return An array of \@c NSXMLElement objects or an empty array if no matching children could be found. + * @details \@method elementsForLocalName:URI \@abstract Returns all of the child elements that match this localname URI pair. * @param local_name Argument converted to the Objective-C parameter of the same role. * @param uri Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -91,116 +91,116 @@ namespace cocoon std::vector elements_for_local_name(const std::string& local_name, const std::string& uri) const; /** * @brief Calls `-[NSXMLElement elementsForName:]`. - * @details Returns the child element nodes (as \@c NSXMLElement objects) of the receiver that have a specified name. If \@c name is a qualified name, then this method invokes \@c elementsForLocalName:URI: with the URI parameter set to the URI associated with the prefix. Otherwise comparison is based on string equality of the qualified or non-qualified name. \@param name A string specifying the name of the child element nodes to find and return. \@return An array of \@c NSXMLElement objects or an empty array if no matching children can be found. + * @details \@method elementsForName: \@abstract Returns all of the child elements that match this name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector elements_for_name(const std::string& name) const; /** * @brief Calls `-[NSXMLElement insertChild:atIndex:]`. - * @details Inserts a new child node at a specified location in the receiver's list of child nodes. Insertion of the node increments the indexes of sibling nodes after it. \@param child An XML node object to be inserted as a child of the receiver. \@param index An integer identifying a position in the receiver's list of children. An exception is raised if \@c index is out of bounds. + * @details \@method insertChild:atIndex: \@abstract Inserts a child at a particular index. * @param child Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_child(const XMLNode& child, std::uint64_t index) const; /** * @brief Calls `-[NSXMLElement insertChildren:atIndex:]`. - * @details Inserts an array of child nodes at a specified location in the receiver's list of children. Insertion of the nodes increases the indexes of sibling nodes after them by the count of \@c children. \@param children An array of XML node objects to add as children of the receiver. \@param index An integer identifying a position in the receiver's list of children. An exception is raised if \@c index is out of bounds. + * @details \@method insertChildren:atIndex: \@abstract Insert several children at a particular index. * @param children Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_children(const std::vector& children, std::uint64_t index) const; /** * @brief Calls `-[NSXMLElement namespaceForPrefix:]`. - * @details Returns the namespace node with a specified prefix. \@param name A string specifying a namespace prefix. \@return An \@c NSXMLNode object of kind \@c NSXMLNamespaceKind or \@c nil if there is no namespace node with that prefix. + * @details \@method namespaceForPrefix: \@abstract Returns the namespace matching this prefix. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ XMLNode namespace_for_prefix(const std::string& name) const; /** * @brief Calls `-[NSXMLElement normalizeAdjacentTextNodesPreservingCDATA:]`. - * @details Coalesces adjacent text nodes of the receiver that you have explicitly added, optionally including CDATA sections. A text node with a value of an empty string is removed. When you process an input source of XML, adjacent text nodes are automatically normalized. You should invoke this method (with \@c preserve as \@c NO) before using the \@c NSXMLNode methods \@c objectsForXQuery:constants:error: or \@c nodesForXPath:error: . \@param preserve \@c YES if CDATA sections are left alone as text nodes, \@c NO otherwise. + * @details \@method normalizeAdjacentTextNodesPreservingCDATA: \@abstract Adjacent text nodes are coalesced. If the node's value is the empty string, it is removed. This should be called with a value of NO before using XQuery or XPath. * @param preserve Argument converted to the Objective-C parameter of the same role. */ void normalize_adjacent_text_nodes_preserving_cdata(bool preserve) const; /** * @brief Calls `-[NSXMLElement removeAttributeForName:]`. - * @details Removes an attribute node identified by name. \@param name A string specifying the name of an attribute. + * @details \@method removeAttributeForName: \@abstract Removes an attribute based on its name. * @param name Argument converted to the Objective-C parameter of the same role. */ void remove_attribute_for_name(const std::string& name) const; /** * @brief Calls `-[NSXMLElement removeChildAtIndex:]`. - * @details Removes the child node of the receiver identified by a given index. The XML node object is released upon removal. The indices of subsequent children are decremented by one. \@param index An integer identifying the node in the receiver's list of children to remove. An exception is raised if \@c index is out of bounds. + * @details \@method removeChildAtIndex:atIndex: \@abstract Removes a child at a particular index. * @param index Argument converted to the Objective-C parameter of the same role. */ void remove_child_at_index(std::uint64_t index) const; /** * @brief Calls `-[NSXMLElement removeNamespaceForPrefix:]`. - * @details Removes a namespace node that is identified by a given prefix. \@param name A string that is the prefix for a namespace. + * @details \@method addNamespace:URI: \@abstract Removes a namespace with a particular name. * @param name Argument converted to the Objective-C parameter of the same role. */ void remove_namespace_for_prefix(const std::string& name) const; /** * @brief Calls `-[NSXMLElement replaceChildAtIndex:withNode:]`. - * @details Replaces a child node at a specified location with another child node. The replaced XML node object is released upon removal. \@param index An integer identifying a position in the receiver's list of children. An exception is raised if \@c index is out of bounds. \@param node An XML node object that will replace the current child. + * @details \@method replaceChildAtIndex:withNode: \@abstract Replaces a child at a particular index with another child. * @param index Argument converted to the Objective-C parameter of the same role. * @param node Argument converted to the Objective-C parameter of the same role. */ void replace_child_at_index(std::uint64_t index, const XMLNode& node) const; /** * @brief Calls `-[NSXMLElement resolveNamespaceForName:]`. - * @details Returns the namespace node with the prefix matching the given qualified name. The method looks in the entire namespace chain for the prefix. \@param name A string that is the qualified name for a namespace (a qualified name is prefix plus local name). \@return An \@c NSXMLNode object of kind \@c NSXMLNamespaceKind or \@c nil if there is no matching namespace node. + * @details \@method resolveNamespaceForName: \@abstract Returns the namespace who matches the prefix of the name given. Looks in the entire namespace chain. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ XMLNode resolve_namespace_for_name(const std::string& name) const; /** * @brief Calls `-[NSXMLElement resolvePrefixForNamespaceURI:]`. - * @details Returns the prefix associated with the specified URI. The method looks in the entire namespace chain for the URI. \@param namespaceURI A string identifying the URI associated with the namespace. \@return A string that is the matching prefix or \@c nil if it finds no matching prefix. + * @details \@method resolvePrefixForNamespaceURI: \@abstract Returns the URI of this prefix. Looks in the entire namespace chain. * @param namespace_uri Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string resolve_prefix_for_namespace_uri(const std::string& namespace_uri) const; /** * @brief Calls `-[NSXMLElement setAttributesAsDictionary:]`. - * @details Sets the attributes based on a name-value dictionary. \@deprecated This method is deprecated because it does not function properly. Use \@c setAttributesWithDictionary: instead. \@param attributes A dictionary of key-value pairs where the attribute name is the key and the object value of the attribute is the dictionary value. + * @details \@method setAttributesAsDictionary: \@abstract Set the attributes base on a name-value dictionary. \@discussion This method is deprecated and does not function correctly. Use -setAttributesWithDictionary: instead. * @param attributes Argument converted to the Objective-C parameter of the same role. */ void set_attributes_as_dictionary(const std::vector>& attributes) const; /** * @brief Calls `-[NSXMLElement setAttributesWithDictionary:]`. - * @details Sets the attributes of the receiver based on a name-value dictionary. The method uses these names and object values to create \@c NSXMLNode objects of kind \@c NSXMLAttributeKind. Existing attributes are removed. \@param attributes A dictionary of key-value pairs where the attribute name is the key and the object value of the attribute is the dictionary value. + * @details \@method setAttributesWithDictionary: \@abstract Set the attributes based on a name-value dictionary. * @param attributes Argument converted to the Objective-C parameter of the same role. */ void set_attributes_with_dictionary(const std::map& attributes) const; /** * @brief Calls `-[NSXMLElement setChildren:]`. - * @details Removes all existing children and replaces them with the new children. Set \@c children to \@c nil to simply remove all children. \@param children An array of \@c NSXMLElement objects or \@c NSXMLNode objects. + * @details \@method setChildren: \@abstract Removes all existing children and replaces them with the new children. Set children to nil to simply remove all children. * @param children Argument converted to the Objective-C parameter of the same role. */ void set_children(const std::vector& children) const; /** * @brief Returns the `attributes` property of `NSXMLElement`. - * @details The attributes of the receiver. In the case of duplicate names, the first attribute with the name is used. To set attributes using an \@c NSDictionary object as the input parameter, see \@c setAttributesWithDictionary: . + * @details \@abstract Set the attributes. In the case of duplicate names, the first attribute with the name is used. * @return The converted Objective-C result. */ std::vector attributes() const; /** * @brief Sets the `attributes` property of `NSXMLElement`. - * @details The attributes of the receiver. In the case of duplicate names, the first attribute with the name is used. To set attributes using an \@c NSDictionary object as the input parameter, see \@c setAttributesWithDictionary: . + * @details \@abstract Set the attributes. In the case of duplicate names, the first attribute with the name is used. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_attributes(const std::vector& value) const; /** * @brief Returns the `namespaces` property of `NSXMLElement`. - * @details The namespace nodes of the receiver. In the case of duplicate names, the first namespace with the name is used. Set to \@c nil to remove all namespace nodes. + * @details \@abstract Set the namespaces. In the case of duplicate names, the first namespace with the name is used. * @return The converted Objective-C result. */ std::vector namespaces() const; /** * @brief Sets the `namespaces` property of `NSXMLElement`. - * @details The namespace nodes of the receiver. In the case of duplicate names, the first namespace with the name is used. Set to \@c nil to remove all namespace nodes. + * @details \@abstract Set the namespaces. In the case of duplicate names, the first namespace with the name is used. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_namespaces(const std::vector& value) const; diff --git a/include/generated/xml_node.h b/include/generated/xml_node.h index 3a0708ce..25356721 100644 --- a/include/generated/xml_node.h +++ b/include/generated/xml_node.h @@ -13,7 +13,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXMLNode` (Foundation). - * @details The nodes in the abstract, logical tree structure that represents an XML document. Node objects can be of different kinds, corresponding to the following markup constructs in an XML document: element, attribute, text, processing instruction, namespace, and comment. In addition, a document-node object (specifically, an instance of ''XMLDocument'') represents an XML document in its entirety. ''XMLNode'' objects can also represent document type declarations as well as declarations in Document Type Definitions (DTDs). Class factory methods of ''XMLNode'' enable you to create nodes of each kind. Only document, element, and DTD nodes may have child nodes. Among the XML family of classes (excluding ''XMLParser'') the ''XMLNode'' class is the base class. Inheriting from it are the classes ''XMLElement'', ''XMLDocument'', ''XMLDTD'', and ''XMLDTDNode''. ''XMLNode'' specifies the interface common to all XML node objects and defines common node behavior and attributes, for example hierarchy level, node name and value, tree traversal, and the ability to emit representative XML markup text. \#\#\# Subclassing Notes You can subclass ''XMLNode'' if you want nodes of kinds different from the supported ones, You can also create a subclass with more specialized attributes or behavior than ''XMLNode''. \#\#\#\# Methods to Override To subclass ''XMLNode'' you need to override the primary initializer, ''init(kind:options:)'', and the methods listed below. In most cases, you need only invoke the superclass implementation, adding any subclass-specific code before or after the invocation, as necessary. | ''kind'' | ''parent'' | |---|---| | ''name'' | ''child(at:)'' | | ''name'' | ''childCount'' | | ''objectValue'' | ''children'' | | ''objectValue'' | ''detach()'' | | ''stringValue'' | ''localName'' | | ''setStringValue(:resolvingEntities:)'' | ''prefix'' | | ''index'' | ''uri'' | By default ''XMLNode'' implements the 'NSObject' \ method to perform a deep comparison: two ''XMLNode'' objects are not considered equal unless they have the same name, same child nodes, same attributes, and so on. The comparison looks at the node and its children, but does not include the node's parent. If you want a different standard of comparison, override 'isEqual:'. \#\#\#\# Special Considerations Because of the architecture and data model of NSXML, when it parses and processes a source of XML it cannot know about your subclass unless you override the ''XMLDocument'' class method ''XMLDocument/replacementClass(for:)'' to return your custom class in place of an NSXML class. If your custom class has no direct NSXML counterpart—for example, it is a subclass of ''XMLNode'' that represents CDATA sections—then you can walk the tree after it has been created and insert the new node where appropriate. + * @details \@class NSXMLNode \@abstract The basic unit of an XML document. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -56,21 +56,21 @@ namespace cocoon explicit XMLNode(Adopt adopt); /** * @brief Calls `+[NSXMLNode DTDNodeWithXMLString:]`. - * @details Returns an \@c NSXMLDTDNode object representing the DTD declaration for an element, attribute, entity, or notation based on a given string. \@c NSXMLNode is able to assign the created node object a kind by parsing the string. Note that if an attribute-list declaration (\@c \\\) has multiple attributes, \@c NSXMLNode only creates an \@c NSXMLDTDNode object for the last attribute in the declaration. \@param string A string that is a DTD declaration. The receiver parses this string to determine the kind of DTD node to create. + * @details \@method DTDNodeWithXMLString: \@abstract Returns an element, attribute, entity, or notation DTD node based on the full XML string. * @param string Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object dtd_node_with_xml_string(const std::string& string); /** * @brief Calls `-[NSXMLNode XMLStringWithOptions:]`. - * @details Returns the string representation of the receiver as it would appear in an XML document, with one or more output options specified. The returned string includes the string representations of all children. \@param options One or more \@c enum constants identifying an output option; bit-OR multiple constants together. + * @details \@method XMLStringWithOptions: \@abstract The representation of this node as it would appear in an XML document, with various output options available. * @param options Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string xml_string_with_options(XMLNodeOptions options) const; /** * @brief Calls `+[NSXMLNode attributeWithName:URI:stringValue:]`. - * @details Returns an \@c NSXMLNode object representing an attribute node with a given qualified name and string. For example, in the attribute "bst:id='12345'", "bst" is the name qualifier (derived from the URI), "id" is the attribute name, and "12345" is the attribute value. \@param name A string that is the name of an attribute. \@param URI A URI (Universal Resource Identifier) that qualifies \@c name. \@param stringValue A string that is the value of the attribute. + * @details \@method attributeWithLocalName:URI:stringValue: \@abstract Returns an attribute whose full QName is specified. * @param name Argument converted to the Objective-C parameter of the same role. * @param uri Argument converted to the Objective-C parameter of the same role. * @param string_value Argument converted to the Objective-C parameter of the same role. @@ -79,7 +79,7 @@ namespace cocoon static Object attribute_with_name(const std::string& name, const std::string& uri, const std::string& string_value); /** * @brief Calls `+[NSXMLNode attributeWithName:stringValue:]`. - * @details Returns an \@c NSXMLNode object representing an attribute node with a given name and string. For example, in the attribute "id='12345'", "id" is the attribute name and "12345" is the attribute value. \@param name A string that is the name of an attribute. \@param stringValue A string that is the value of an attribute. + * @details \@method attributeWithName:stringValue: \@abstract Returns an attribute \name="stringValue"\. * @param name Argument converted to the Objective-C parameter of the same role. * @param string_value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -87,53 +87,53 @@ namespace cocoon static Object attribute_with_name(const std::string& name, const std::string& string_value); /** * @brief Calls `-[NSXMLNode canonicalXMLStringPreservingComments:]`. - * @details Returns a string object encapsulating the receiver's XML in canonical form. Be sure to set the input option \@c NSXMLNodePreserveWhitespace for true canonical form. The canonical form of an XML document is defined by the World Wide Web Consortium at http://www.w3.org/TR/xml-c14n. \@param comments \@c YES to preserve comments, \@c NO otherwise. + * @details \@method canonicalXMLStringPreservingComments: \@abstract W3 canonical form (http://www.w3.org/TR/xml-c14n). The input option NSXMLNodePreserveWhitespace should be set for true canonical form. * @param comments Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::string canonical_xml_string_preserving_comments(bool comments) const; /** * @brief Calls `-[NSXMLNode childAtIndex:]`. - * @details Returns the child node of the receiver at the specified location. The receiver should be an \@c NSXMLNode object representing a document, element, or document type declaration. The returned node object can represent an element, comment, text, or processing instruction. \@param index An integer specifying a node position in the receiver's array of children. If \@c index is out of bounds, an exception is raised. + * @details \@method childAtIndex: \@abstract Returns the child node at a particular index. * @param index Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ XMLNode child_at_index(std::uint64_t index) const; /** * @brief Calls `+[NSXMLNode commentWithStringValue:]`. - * @details Returns an \@c NSXMLNode object representing a comment node containing given text. \@param stringValue A string specifying the text of the comment. You may specify \@c nil or an empty string. + * @details \@method commentWithStringValue: \@abstract Returns a comment \<--stringValue-->\. * @param string_value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object comment_with_string_value(const std::string& string_value); /** * @brief Calls `-[NSXMLNode detach]`. - * @details Detaches the receiver from its parent node. This method is applicable to \@c NSXMLNode objects representing elements, text, comments, processing instructions, attributes, and namespaces. Once the node object is detached, you can add it as a child node of another parent. + * @details \@method detach: \@abstract Detaches this node from its parent. */ void detach() const; /** * @brief Calls `+[NSXMLNode document]`. - * @details Returns an empty document node. Returns an \@c NSXMLDocument instance without a root element or XML-declaration information (version, encoding, standalone flag). Returns \@c nil if the object couldn't be created. + * @details \@method document: \@abstract Returns an empty document. * @return The converted Objective-C result. */ static Object document(); /** * @brief Calls `+[NSXMLNode documentWithRootElement:]`. - * @details Returns an \@c NSXMLDocument object initialized with a given root element. \@param element An \@c NSXMLElement object representing an element. + * @details \@method documentWithRootElement: \@abstract Returns a document \@param element The document's root node. * @param element Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object document_with_root_element(const XMLElement& element); /** * @brief Calls `+[NSXMLNode elementWithName:]`. - * @details Returns an \@c NSXMLElement object with a given tag identifier, or name. The equivalent XML markup is \@c \\\\\\ . \@param name A string that is the name (or tag identifier) of an element. + * @details \@method elementWithName: \@abstract Returns an element \<name></name>\. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object element_with_name(const std::string& name); /** * @brief Calls `+[NSXMLNode elementWithName:URI:]`. - * @details Returns an element whose fully qualified name is specified. \@param name A string that is the name (or tag identifier) of an element. \@param URI A URI (Universal Resource Identifier) that qualifies \@c name. + * @details \@method elementWithName:URI: \@abstract Returns an element whose full QName is specified. * @param name Argument converted to the Objective-C parameter of the same role. * @param uri Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -141,7 +141,7 @@ namespace cocoon static Object element_with_name(const std::string& name, const std::string& uri); /** * @brief Calls `+[NSXMLNode elementWithName:children:attributes:]`. - * @details Returns an \@c NSXMLElement object with the given tag (name), attributes, and children. \@param name A string that is the name (tag identifier) of the element. \@param children An array of \@c NSXMLElement objects or \@c NSXMLNode objects. Specify \@c nil if there are no children to add to this node object. \@param attributes An array of \@c NSXMLNode objects of kind \@c NSXMLAttributeKind. Specify \@c nil if there are no attributes to add to this node object. + * @details \@method elementWithName:children:attributes: \@abstract Returns an element children and attributes \<name attr1="foo" attr2="bar"><-- child1 -->child2</name>\. * @param name Argument converted to the Objective-C parameter of the same role. * @param children Argument converted to the Objective-C parameter of the same role. * @param attributes Argument converted to the Objective-C parameter of the same role. @@ -150,14 +150,14 @@ namespace cocoon static Object element_with_name(const std::string& name, const std::vector& children, const std::vector& attributes); /** * @brief Calls `+[NSXMLNode localNameForName:]`. - * @details Returns the local name from the specified qualified name. For example, if the qualified name is "bst:title", this method returns "title". \@param name A string that is a qualified name. + * @details \@method localNameForName: \@abstract Returns the local name bar in foo:bar. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string local_name_for_name(const std::string& name); /** * @brief Calls `+[NSXMLNode namespaceWithName:stringValue:]`. - * @details Returns an \@c NSXMLNode object representing a namespace with a specified name and URI. The equivalent namespace declaration in XML markup is \@c xmlns:name="value" . \@param name A string that is the name of the namespace. Specify an empty string for \@c name to get the default namespace. \@param stringValue A string that identifies the URI associated with the namespace. + * @details \@method namespaceWithName:stringValue: \@abstract Returns a namespace \xmlns:name="stringValue"\. * @param name Argument converted to the Objective-C parameter of the same role. * @param string_value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -165,14 +165,14 @@ namespace cocoon static Object namespace_with_name(const std::string& name, const std::string& string_value); /** * @brief Calls `-[NSXMLNode nodesForXPath:error:]`. - * @details Returns the nodes resulting from executing an XPath query upon the receiver. The receiver acts as the context item for the query ("."). If you have explicitly added adjacent text nodes as children of an element, you should invoke the \@c NSXMLElement method \@c normalizeAdjacentTextNodesPreservingCDATA: (with an argument of \@c NO) on the element before applying any XPath queries to it; this method coalesces these text nodes. \@param xpath A string that expresses an XPath query. \@param error If query errors occur, indirectly returns an \@c NSError object describing the errors. \@return An array of \@c NSXMLNode objects that match the query, or an empty array if there are no matches. + * @details \@method nodesForXPath:error: \@abstract Returns the nodes resulting from applying an XPath to this node using the node as the context item ("."). normalizeAdjacentTextNodesPreservingCDATA:NO should be called if there are adjacent text nodes since they are not allowed under the XPath/XQuery Data Model. \@returns An array whose elements are a kind of NSXMLNode. * @param xpath Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector nodes_for_x_path(const std::string& xpath) const; /** * @brief Calls `-[NSXMLNode objectsForXQuery:constants:error:]`. - * @details Returns the objects resulting from executing an XQuery query upon the receiver. The receiver acts as the context item for the query ("."). If the receiver has been changed after parsing to have multiple adjacent text nodes, you should invoke the \@c NSXMLElement method \@c normalizeAdjacentTextNodesPreservingCDATA: (with an argument of \@c NO) to coalesce the text nodes before querying. \@param xquery A string that expresses an XQuery query. \@param constants A dictionary containing externally declared constants where the name of each constant variable is a key. \@param error If query errors occur, indirectly returns an \@c NSError object describing the errors. \@return An array whose elements are kinds of \@c NSArray, \@c NSData, \@c NSDate, \@c NSNumber, \@c NSString, \@c NSURL, or \@c NSXMLNode. + * @details \@method objectsForXQuery:constants:error: \@abstract Returns the objects resulting from applying an XQuery to this node using the node as the context item ("."). Constants are a name-value dictionary for constants declared "external" in the query. normalizeAdjacentTextNodesPreservingCDATA:NO should be called if there are adjacent text nodes since they are not allowed under the XPath/XQuery Data Model. \@returns An array whose elements are kinds of NSArray, NSData, NSDate, NSNumber, NSString, NSURL, or NSXMLNode. * @param xquery Argument converted to the Objective-C parameter of the same role. * @param constants Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -180,28 +180,27 @@ namespace cocoon std::vector objects_for_x_query(const std::string& xquery, const std::map& constants) const; /** * @brief Calls `-[NSXMLNode objectsForXQuery:error:]`. - * @details Returns the objects resulting from executing an XQuery query upon the receiver. This convenience method invokes \@c objectsForXQuery:constants:error: with \@c nil for the \@c constants dictionary. \@param xquery A string that expresses an XQuery query. \@param error If query errors occur, indirectly returns an \@c NSError object describing the errors. * @param xquery Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ std::vector objects_for_x_query(const std::string& xquery) const; /** * @brief Calls `+[NSXMLNode predefinedNamespaceForPrefix:]`. - * @details Returns an \@c NSXMLNode object representing one of the predefined namespaces with the specified prefix. \@param name A string specifying a prefix for a predefined namespace, for example "xml", "xs", or "xsi". If something other than a predefined-namespace prefix is specified, the method returns \@c nil. + * @details \@method predefinedNamespaceForPrefix: \@abstract Returns the namespace belonging to one of the predefined namespaces xml, xs, or xsi * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static XMLNode predefined_namespace_for_prefix(const std::string& name); /** * @brief Calls `+[NSXMLNode prefixForName:]`. - * @details Returns the prefix from the specified qualified name. For example, if the qualified name is "bst:title", this method returns "bst". \@param name A string that is a qualified name. + * @details \@method localNameForName: \@abstract Returns the prefix foo in the name foo:bar. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static std::string prefix_for_name(const std::string& name); /** * @brief Calls `+[NSXMLNode processingInstructionWithName:stringValue:]`. - * @details Returns an \@c NSXMLNode object representing a processing instruction with a specified name and value. The equivalent XML markup is \@c \\\ . \@param name A string that is the name of the processing instruction. \@param stringValue A string that is the value of the processing instruction. + * @details \@method processingInstructionWithName:stringValue: \@abstract Returns a processing instruction \<?name stringValue>\. * @param name Argument converted to the Objective-C parameter of the same role. * @param string_value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -209,51 +208,51 @@ namespace cocoon static Object processing_instruction_with_name(const std::string& name, const std::string& string_value); /** * @brief Calls `-[NSXMLNode setStringValue:resolvingEntities:]`. - * @details Sets the content as with \@c setStringValue:, but when \@c resolve is \@c YES, character references, predefined entities and user entities available in the document's DTD are resolved. Entities not available in the DTD remain in their entity form. User-defined entities not declared in the DTD remain in their unresolved form. This method can only be invoked on \@c NSXMLNode objects that may have content. Setting the string value of a node object removes all existing children, including processing instructions and comments. Setting the string value of an element node object creates a text node as the sole child. \@param string A string to assign as the value of the receiver. \@param resolve \@c YES to resolve character references, predefined entities, and user-defined entities as declared in the associated DTD; \@c NO otherwise. + * @details \@method setStringValue:resolvingEntities: \@abstract Sets the content as with \@link setStringValue: \@/link, but when "resolve" is true, character references, predefined entities and user entities available in the document's dtd are resolved. Entities not available in the dtd remain in their entity form. * @param string Argument converted to the Objective-C parameter of the same role. * @param resolve Argument converted to the Objective-C parameter of the same role. */ void set_string_value(const std::string& string, bool resolve) const; /** * @brief Calls `+[NSXMLNode textWithStringValue:]`. - * @details Returns an \@c NSXMLNode object representing a text node with specified content. \@param stringValue A string that is the textual content of the node. + * @details \@method textWithStringValue: \@abstract Returns a text node. * @param string_value Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static Object text_with_string_value(const std::string& string_value); /** * @brief Returns the `URI` property of `NSXMLNode`. - * @details The URI associated with the receiver. A node's URI is derived from its namespace or a document's URI; for documents, the URI comes either from the parsed XML or is explicitly set. You cannot change the URI for a particular node other than for a namespace or document node. + * @details \@abstract Set the URI of this element, attribute, or document. For documents it is the URI of document origin. Getter returns the URI of this element, attribute, or document. For documents it is the URI of document origin and is automatically set when using initWithContentsOfURL. * @return The converted Objective-C result. */ std::string uri() const; /** * @brief Sets the `URI` property of `NSXMLNode`. - * @details The URI associated with the receiver. A node's URI is derived from its namespace or a document's URI; for documents, the URI comes either from the parsed XML or is explicitly set. You cannot change the URI for a particular node other than for a namespace or document node. + * @details \@abstract Set the URI of this element, attribute, or document. For documents it is the URI of document origin. Getter returns the URI of this element, attribute, or document. For documents it is the URI of document origin and is automatically set when using initWithContentsOfURL. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_uri(const std::string& value) const; /** * @brief Returns the `XMLString` property of `NSXMLNode`. - * @details The string representation of the receiver as it would appear in an XML document. The returned string includes the string representations of all children. This property invokes \@c XMLStringWithOptions: with an \@c options argument of \@c NSXMLNodeOptionsNone. + * @details \@abstract The representation of this node as it would appear in an XML document. * @return The converted Objective-C result. */ std::string xml_string() const; /** * @brief Returns the `XPath` property of `NSXMLNode`. - * @details The XPath expression identifying the receiver's location in the document tree. For example, this property might return a string such as "foo/bar[2]/baz". The result of this property can be used directly in the \@c nodesForXPath:error: and \@c objectsForXQuery:constants:error: methods. + * @details \@abstract Returns the XPath to this node, for example foo/bar[2]/baz. * @return The converted Objective-C result. */ std::string x_path() const; /** * @brief Returns the `childCount` property of `NSXMLNode`. - * @details The number of child nodes the receiver has. The receiver should be an \@c NSXMLNode object representing a document, element, or document type declaration. For performance reasons, use this property instead of getting the count from the array returned by \@c children. + * @details \@abstract The amount of children, relevant for documents, elements, and document type declarations. Use this instead of [[self children] count]. * @return The converted Objective-C result. */ std::uint64_t child_count() const; /** * @brief Returns the `children` property of `NSXMLNode`. - * @details An immutable array containing the child nodes of the receiver (as \@c NSXMLNode objects). + * @details \@abstract An immutable array of child nodes. Relevant for documents, elements, and document type declarations. * @return The converted Objective-C result. */ std::vector children() const; @@ -265,103 +264,103 @@ namespace cocoon std::string description() const; /** * @brief Returns the `index` property of `NSXMLNode`. - * @details The index of the receiver identifying its position relative to its sibling nodes. The first child node of a parent has an index of zero. + * @details \@abstract A node's index amongst its siblings. * @return The converted Objective-C result. */ std::uint64_t index() const; /** * @brief Returns the `kind` property of `NSXMLNode`. - * @details Returns the kind of node the receiver is as a constant of type \@c NSXMLNodeKind. \@c NSXMLNode objects can represent documents, elements, attributes, namespaces, text, processing instructions, comments, document type declarations, and specific declarations within DTDs. + * @details \@abstract Returns an element, attribute, entity, or notation DTD node based on the full XML string. * @return The converted Objective-C result. */ XMLNodeKind kind() const; /** * @brief Returns the `level` property of `NSXMLNode`. - * @details The nesting level of the receiver within the tree hierarchy. The root element of a document has a nesting level of one. + * @details \@abstract The depth of the node within the tree. Documents and standalone nodes are level 0. * @return The converted Objective-C result. */ std::uint64_t level() const; /** * @brief Returns the `localName` property of `NSXMLNode`. - * @details The local name of the receiver. The local name is the part of a node name that follows a namespace-qualifying colon or the full name if there is no colon. For example, "chapter" is the local name in the qualified name "acme:chapter". + * @details \@abstract Returns the local name bar if this attribute or element's name is foo:bar * @return The converted Objective-C result. */ std::string local_name() const; /** * @brief Returns the `name` property of `NSXMLNode`. - * @details The name of the receiver. This property is applicable only to \@c NSXMLNode objects representing elements, attributes, namespaces, processing instructions, and DTD-declaration nodes. If the receiver is not an object of one of these kinds, this property returns \@c nil. If the name is associated with a namespace, the qualified name is returned. + * @details \@abstract Sets the nodes name. Applicable for element, attribute, namespace, processing-instruction, document type declaration, element declaration, attribute declaration, entity declaration, and notation declaration. * @return The converted Objective-C result. */ std::string name() const; /** * @brief Sets the `name` property of `NSXMLNode`. - * @details The name of the receiver. This property is applicable only to \@c NSXMLNode objects representing elements, attributes, namespaces, processing instructions, and DTD-declaration nodes. If the receiver is not an object of one of these kinds, this property returns \@c nil. If the name is associated with a namespace, the qualified name is returned. + * @details \@abstract Sets the nodes name. Applicable for element, attribute, namespace, processing-instruction, document type declaration, element declaration, attribute declaration, entity declaration, and notation declaration. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_name(const std::string& value) const; /** * @brief Returns the `nextNode` property of `NSXMLNode`. - * @details The next \@c NSXMLNode object in document order. You use this property to "walk" forward through the tree structure representing an XML document or document section. Document order is the natural order that XML constructs appear in markup text. If you send this message to the last node in the tree, \@c nil is returned. \@c NSXMLNode bypasses namespace and attribute nodes when it traverses a tree in document order. + * @details \@abstract Returns the next node in document order. This can be used to walk the tree forwards. * @return The converted Objective-C result. */ XMLNode next_node() const; /** * @brief Returns the `nextSibling` property of `NSXMLNode`. - * @details The next \@c NSXMLNode object that is a sibling node to the receiver. This object will have an index value that is one more than the receiver's. If there are no more subsequent siblings (that is, other child nodes of the receiver's parent) the property returns \@c nil. + * @details \@abstract Returns the next sibling, or nil if there isn't one. * @return The converted Objective-C result. */ XMLNode next_sibling() const; /** * @brief Returns the `objectValue` property of `NSXMLNode`. - * @details The object value of the receiver. The object value may be the same as the value returned by \@c stringValue. For nodes without content (for example, document nodes), this property returns the string value, or an empty string if there is no string value. + * @details \@abstract Sets the content of the node. Setting the objectValue removes all existing children including processing instructions and comments. Setting the object value on an element creates a single text node child. * @return The converted Objective-C result. */ Object object_value() const; /** * @brief Sets the `objectValue` property of `NSXMLNode`. - * @details The object value of the receiver. The object value may be the same as the value returned by \@c stringValue. For nodes without content (for example, document nodes), this property returns the string value, or an empty string if there is no string value. + * @details \@abstract Sets the content of the node. Setting the objectValue removes all existing children including processing instructions and comments. Setting the object value on an element creates a single text node child. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_object_value(const Object& value) const; /** * @brief Returns the `parent` property of `NSXMLNode`. - * @details The parent node of the receiver. Document nodes and standalone nodes (that is, the root of a detached branch of a tree) have no parent, and sending this message to them returns \@c nil. A one-to-one relationship does not always exist between a parent and its children; although a namespace or attribute node cannot be a child, it still has a parent element. + * @details \@abstract The parent of this node. Documents and standalone Nodes have a nil parent; there is not a 1-to-1 relationship between parent and children, eg a namespace cannot be a child but has a parent element. * @return The converted Objective-C result. */ XMLNode parent() const; /** * @brief Returns the `prefix` property of `NSXMLNode`. - * @details The prefix of the receiver's name. The prefix is the part of a namespace-qualified name that precedes the colon. For example, "acme" is the prefix in the qualified name "acme:chapter". Returns an empty string if the receiver's name is not qualified by a namespace. + * @details \@abstract Returns the prefix foo if this attribute or element's name if foo:bar * @return The converted Objective-C result. */ std::string prefix() const; /** * @brief Returns the `previousNode` property of `NSXMLNode`. - * @details The previous \@c NSXMLNode object in document order. You use this property to "walk" backward through the tree structure representing an XML document or document section. Document order is the natural order that XML constructs appear in markup text. If you send this message to the first node in the tree (that is, the root element), \@c nil is returned. \@c NSXMLNode bypasses namespace and attribute nodes when it traverses a tree in document order. + * @details \@abstract Returns the previous node in document order. This can be used to walk the tree backwards. * @return The converted Objective-C result. */ XMLNode previous_node() const; /** * @brief Returns the `previousSibling` property of `NSXMLNode`. - * @details The previous \@c NSXMLNode object that is a sibling node to the receiver. This object will have an index value that is one less than the receiver's. If there are no more previous siblings (that is, other child nodes of the receiver's parent) the property returns \@c nil. + * @details \@abstract Returns the previous sibling, or nil if there isn't one. * @return The converted Objective-C result. */ XMLNode previous_sibling() const; /** * @brief Returns the `rootDocument` property of `NSXMLNode`. - * @details The \@c NSXMLDocument object containing the root element and representing the XML document as a whole. If the receiver is a standalone node (that is, a node at the head of a detached branch of the tree), this property returns \@c nil. + * @details \@abstract The encompassing document or nil. * @return The converted Objective-C result. */ XMLDocument root_document() const; /** * @brief Returns the `stringValue` property of `NSXMLNode`. - * @details The content of the receiver as a string value. If the receiver is a node object of element kind, the content is that of any text-node children. This method recursively visits element nodes and concatenates their text nodes in document order with no intervening spaces. + * @details \@abstract Sets the content of the node. Setting the stringValue removes all existing children including processing instructions and comments. Setting the string value on an element creates a single text node child. The getter returns the string value of the node, which may be either its content or child text nodes, depending on the type of node. Elements are recursed and text nodes concatenated in document order with no intervening spaces. * @return The converted Objective-C result. */ std::string string_value() const; /** * @brief Sets the `stringValue` property of `NSXMLNode`. - * @details The content of the receiver as a string value. If the receiver is a node object of element kind, the content is that of any text-node children. This method recursively visits element nodes and concatenates their text nodes in document order with no intervening spaces. + * @details \@abstract Sets the content of the node. Setting the stringValue removes all existing children including processing instructions and comments. Setting the string value on an element creates a single text node child. The getter returns the string value of the node, which may be either its content or child text nodes, depending on the type of node. Elements are recursed and text nodes concatenated in document order with no intervening spaces. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_string_value(const std::string& value) const; diff --git a/include/generated/xml_parser.h b/include/generated/xml_parser.h index bf564cae..23585bdf 100644 --- a/include/generated/xml_parser.h +++ b/include/generated/xml_parser.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXMLParser` (Foundation). - * @details An event driven parser of XML documents (including DTD declarations). An ''XMLParser'' notifies its delegate about the items (elements, attributes, CDATA blocks, comments, and so on) that it encounters as it processes an XML document. It does not itself do anything with those parsed items except report them. It also reports parsing errors. For convenience, an ''XMLParser'' object in the following descriptions is sometimes referred to as a parser object. Unless used in a callback, the ''XMLParser'' is a thread-safe class as long as any given instance is only used in one thread. > Note: > Namespace support was implemented in ''XMLParser'' starting in macOS 10.4. Namespace-related methods of ''XMLParser'' prior to this version have no effect. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -60,102 +59,85 @@ namespace cocoon explicit XMLParser(Adopt adopt); /** * @brief Calls `-[NSXMLParser abortParsing]`. - * @details Stops the parser object. If you invoke this method, the delegate, if it implements '-parser:parseErrorOccurred:', is informed of the cancelled parsing operation. */ void abort_parsing() const; /** * @brief Calls `-[NSXMLParser parse]`. - * @details Starts the event-driven parsing operation. - Returns: 'YES' if the parsing operation succeeds; 'NO' if an error occurs or if the parsing operation aborts. * @return The converted Objective-C result. */ bool parse() const; /** * @brief Returns the `allowedExternalEntityURLs` property of `NSXMLParser`. - * @details The set of external entity URLs that the parser is allowed to load. * @return The converted Objective-C result. */ std::vector allowed_external_entity_urls() const; /** * @brief Sets the `allowedExternalEntityURLs` property of `NSXMLParser`. - * @details The set of external entity URLs that the parser is allowed to load. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_allowed_external_entity_urls(const std::vector& value) const; /** * @brief Returns the `columnNumber` property of `NSXMLParser`. - * @details The column number of the XML document being processed by the parser. The column refers to the nesting level of the XML elements in the document. You may access this property once a parsing operation has begun or after an error occurs. * @return The converted Objective-C result. */ std::int64_t column_number() const; /** * @brief Returns the `externalEntityResolvingPolicy` property of `NSXMLParser`. - * @details The external entity resolving policy for the parser. Defaults to 'NSXMLParserResolveExternalEntitiesNever'. * @return The converted Objective-C result. */ XMLParserExternalEntityResolvingPolicy external_entity_resolving_policy() const; /** * @brief Sets the `externalEntityResolvingPolicy` property of `NSXMLParser`. - * @details The external entity resolving policy for the parser. Defaults to 'NSXMLParserResolveExternalEntitiesNever'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_external_entity_resolving_policy(XMLParserExternalEntityResolvingPolicy value) const; /** * @brief Returns the `lineNumber` property of `NSXMLParser`. - * @details The line number of the XML document being processed by the parser. You may access this property once a parsing operation has begun or after an error occurs. * @return The converted Objective-C result. */ std::int64_t line_number() const; /** * @brief Returns the `parserError` property of `NSXMLParser`. - * @details An 'NSError' object from which you can obtain information about a parsing error. You may access this property after a parsing operation abnormally terminates to determine the cause of error. * @return The converted Objective-C result. */ Error parser_error() const; /** * @brief Returns the `publicID` property of `NSXMLParser`. - * @details The public identifier of the external entity referenced in the XML document. You may access this property once a parsing operation has begun or after an error occurs. * @return The converted Objective-C result. */ std::string public_id() const; /** * @brief Returns the `shouldProcessNamespaces` property of `NSXMLParser`. - * @details A Boolean value that determines whether the parser reports the namespaces and qualified names of elements. 'YES' if the parser reports namespace and qualified name, 'NO' otherwise. The parser reports element names with the delegate methods '-parser:didStartElement:namespaceURI:qualifiedName:attributes:' and '-parser:didEndElement:namespaceURI:qualifiedName:'. * @return The converted Objective-C result. */ bool should_process_namespaces() const; /** * @brief Sets the `shouldProcessNamespaces` property of `NSXMLParser`. - * @details A Boolean value that determines whether the parser reports the namespaces and qualified names of elements. 'YES' if the parser reports namespace and qualified name, 'NO' otherwise. The parser reports element names with the delegate methods '-parser:didStartElement:namespaceURI:qualifiedName:attributes:' and '-parser:didEndElement:namespaceURI:qualifiedName:'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_should_process_namespaces(bool value) const; /** * @brief Returns the `shouldReportNamespacePrefixes` property of `NSXMLParser`. - * @details A Boolean value that determines whether the parser reports the prefixes indicating the scope of namespace declarations. 'YES' if the parser reports the scope of namespace declarations, 'NO' otherwise. The default value is 'NO'. The parser reports prefixes with the delegate methods '-parser:didStartMappingPrefix:toURI:' and '-parser:didEndMappingPrefix:'. * @return The converted Objective-C result. */ bool should_report_namespace_prefixes() const; /** * @brief Sets the `shouldReportNamespacePrefixes` property of `NSXMLParser`. - * @details A Boolean value that determines whether the parser reports the prefixes indicating the scope of namespace declarations. 'YES' if the parser reports the scope of namespace declarations, 'NO' otherwise. The default value is 'NO'. The parser reports prefixes with the delegate methods '-parser:didStartMappingPrefix:toURI:' and '-parser:didEndMappingPrefix:'. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_should_report_namespace_prefixes(bool value) const; /** * @brief Returns the `shouldResolveExternalEntities` property of `NSXMLParser`. - * @details A Boolean value that determines whether the parser reports declarations of external entities. 'YES' if the parser reports declarations of external entities, 'NO' otherwise. The default value is 'NO'. If you set this property to 'YES', you may cause other I/O operations, either network-based or disk-based, to load the external DTD. Toggles between disabling external entities entirely, and the current setting of the 'externalEntityResolvingPolicy'. The 'externalEntityResolvingPolicy' property should be used instead of this, unless targeting 10.9/7.0 or earlier. * @return The converted Objective-C result. */ bool should_resolve_external_entities() const; /** * @brief Sets the `shouldResolveExternalEntities` property of `NSXMLParser`. - * @details A Boolean value that determines whether the parser reports declarations of external entities. 'YES' if the parser reports declarations of external entities, 'NO' otherwise. The default value is 'NO'. If you set this property to 'YES', you may cause other I/O operations, either network-based or disk-based, to load the external DTD. Toggles between disabling external entities entirely, and the current setting of the 'externalEntityResolvingPolicy'. The 'externalEntityResolvingPolicy' property should be used instead of this, unless targeting 10.9/7.0 or earlier. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_should_resolve_external_entities(bool value) const; /** * @brief Returns the `systemID` property of `NSXMLParser`. - * @details The system identifier of the external entity referenced in the XML document. You may access this property once a parsing operation has begun or after an error occurs. * @return The converted Objective-C result. */ std::string system_id() const; diff --git a/include/generated/xmldtd.h b/include/generated/xmldtd.h index 224ce235..dbf63993 100644 --- a/include/generated/xmldtd.h +++ b/include/generated/xmldtd.h @@ -14,7 +14,7 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXMLDTD` (Foundation). - * @details A representation of a Document Type Definition. An instance of the ''XMLDTD'' class is held as a property of an ''XMLDocument'' instance, accessed through the ''XMLDocument'' property ''XMLDocument/dtd''. In the data model, an ''XMLDTD'' object is conceptually similar to namespace and attribute nodes: it is not considered to be a child of the ''XMLDocument'' object although it is closely associated with it. It is at the "root" of a shallow tree consisting primarily of nodes representing DTD declarations. Acceptable child nodes are instances of the ''XMLDTDNode'' class as well as ''XMLNode'' objects representing comment nodes and processing-instruction nodes. You create an 'NSXMLDTD' object in one of three ways: - By processing an XML document with its own internal (in-line) DTD - By process a standalone (external) DTD - Programmatically Once an ''XMLDTD'' instance is in place, you can add, remove, and change the ''XMLDTDNode'' objects representing various DTD declarations. When you write the document out as XML, the new or modified internal DTD is included (assuming you set the DTD in the ''XMLDocument'' instance). You may also programmatically create an external DTD and write that out to its own file. + * @details \@class NSXMLDTD \@abstract Defines the order, repetition, and allowable values for a document * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref XMLNode. * @@ -55,13 +55,13 @@ namespace cocoon explicit XMLDTD(Adopt adopt); /** * @brief Calls `-[NSXMLDTD addChild:]`. - * @details Adds a child node to the end of the list of existing children. - Parameter child: The node object to add to the existing children. + * @details \@method addChild: \@abstract Adds a child to the end of the existing children. * @param child Argument converted to the Objective-C parameter of the same role. */ void add_child(const XMLNode& child) const; /** * @brief Calls `-[NSXMLDTD attributeDeclarationForName:elementName:]`. - * @details Returns the DTD node representing an attribute-list declaration for a given attribute and its element. - Parameters: - name: A string object identifying the name of an attribute. - elementName: A string object identifying the name of an element. - Returns: An autoreleased ''XMLDTDNode'' object, or 'nil' if there is no matching attribute-list declaration. For example, in the attribute-list declaration '\', "idnum" would correspond to 'attrName' and "person" would correspond to 'elementName'. + * @details \@method attributeDeclarationForName: \@abstract Returns the attribute declaration matching this name. * @param name Argument converted to the Objective-C parameter of the same role. * @param element_name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -69,86 +69,86 @@ namespace cocoon XMLDTDNode attribute_declaration_for_name(const std::string& name, const std::string& element_name) const; /** * @brief Calls `-[NSXMLDTD elementDeclarationForName:]`. - * @details Returns the DTD node representing an element declaration for a specified element. - Parameter name: A string that is the name of an element. - Returns: An autoreleased ''XMLDTDNode'' object, or 'nil' if there is no match. + * @details \@method elementDeclarationForName: \@abstract Returns the element declaration matching this name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ XMLDTDNode element_declaration_for_name(const std::string& name) const; /** * @brief Calls `-[NSXMLDTD entityDeclarationForName:]`. - * @details Returns the DTD node representing the entity declaration matching this name. - Parameter name: A string that is the name of an entity. - Returns: An autoreleased ''XMLDTDNode'' object, or 'nil' if there is no match. + * @details \@method entityDeclarationForName: \@abstract Returns the entity declaration matching this name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ XMLDTDNode entity_declaration_for_name(const std::string& name) const; /** * @brief Calls `-[NSXMLDTD insertChild:atIndex:]`. - * @details Inserts a child node in the receiver's list of children at a specific location in the list. - Parameters: - child: An XML-node object that represents the child to insert. - index: An integer identifying the location in the receiver's list of children to insert 'child'. The indices of subsequent children in the list are incremented by one. + * @details \@method insertChild:atIndex: \@abstract Inserts a child at a particular index. * @param child Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_child(const XMLNode& child, std::uint64_t index) const; /** * @brief Calls `-[NSXMLDTD insertChildren:atIndex:]`. - * @details Inserts an array of child nodes at a specified location in the receiver's list of children. - Parameters: - children: An array of ''XMLNode'' objects to insert as children of the receiver. - index: An integer identifying the location in the list of current children to make the insertion. The indices of subsequent children in the list are incremented by the number of inserted children. + * @details \@method insertChildren:atIndex: \@abstract Insert several children at a particular index. * @param children Argument converted to the Objective-C parameter of the same role. * @param index Argument converted to the Objective-C parameter of the same role. */ void insert_children(const std::vector& children, std::uint64_t index) const; /** * @brief Calls `-[NSXMLDTD notationDeclarationForName:]`. - * @details Returns the DTD node representing the notation declaration identified by the specified notation name. - Parameter name: A string that is the name of a notation. - Returns: An autoreleased ''XMLDTDNode'' object, or 'nil' if there is no match. + * @details \@method notationDeclarationForName: \@abstract Returns the notation declaration matching this name. * @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ XMLDTDNode notation_declaration_for_name(const std::string& name) const; /** * @brief Calls `+[NSXMLDTD predefinedEntityDeclarationForName:]`. - * @details Returns a DTD node representing the predefined entity declaration with the specified name. - Parameter name: A string identifying a predefined entity declaration. - Returns: An autoreleased ''XMLDTDNode'' object, or 'nil' if there is no match for 'name'. The five predefined entity references (or character references) are '<' (less-than sign), '>' (greater-than sign), '&' (ampersand), '"' (quotation mark), and ''' (apostrophe). + * @details \@method predefinedEntityDeclarationForName: \@abstract Returns the predefined entity declaration matching this name. \@discussion The five predefined entities are \
    \
  • &lt; - <\
  • \
  • &gt; - >\
  • \
  • &amp; - &\
  • \
  • &quot; - "\
  • \
  • &apos; - &\
  • \
* @param name Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static XMLDTDNode predefined_entity_declaration_for_name(const std::string& name); /** * @brief Calls `-[NSXMLDTD removeChildAtIndex:]`. - * @details Removes the child node at a particular location in the receiver's list of children. - Parameter index: An integer identifying the child node to remove. The indices of subsequent children in the list are decremented by one. The removed child node is released. + * @details \@method removeChildAtIndex: \@abstract Removes a child at a particular index. * @param index Argument converted to the Objective-C parameter of the same role. */ void remove_child_at_index(std::uint64_t index) const; /** * @brief Calls `-[NSXMLDTD replaceChildAtIndex:withNode:]`. - * @details Replaces a child at a particular index with another child. - Parameters: - index: An integer identifying the position of a node in the receiver's list of child nodes. - node: An ''XMLNode'' object to replace the object at 'index'. The replaced child node is released. + * @details \@method replaceChildAtIndex:withNode: \@abstract Replaces a child at a particular index with another child. * @param index Argument converted to the Objective-C parameter of the same role. * @param node Argument converted to the Objective-C parameter of the same role. */ void replace_child_at_index(std::uint64_t index, const XMLNode& node) const; /** * @brief Calls `-[NSXMLDTD setChildren:]`. - * @details Removes all existing children of the receiver and replaces them with an array of new child nodes. - Parameter children: An array of ''XMLNode'' objects. To remove all existing children, pass in 'nil'. Replaced or removed child nodes are released. + * @details \@method setChildren: \@abstract Removes all existing children and replaces them with the new children. Set children to nil to simply remove all children. * @param children Argument converted to the Objective-C parameter of the same role. */ void set_children(const std::vector& children) const; /** * @brief Returns the `publicID` property of `NSXMLDTD`. - * @details Returns the receiver's public identifier. This identifier should be in the default catalog in '/etc/xml/catalog' or in a path specified by the environment variable 'XML_CATALOG_FILES'. When the public id is set the system id must also be set. + * @details \@abstract Sets the public id. This identifier should be in the default catalog in /etc/xml/catalog or in a path specified by the environment variable XML_CATALOG_FILES. When the public id is set the system id must also be set. * @return The converted Objective-C result. */ std::string public_id() const; /** * @brief Sets the `publicID` property of `NSXMLDTD`. - * @details Returns the receiver's public identifier. This identifier should be in the default catalog in '/etc/xml/catalog' or in a path specified by the environment variable 'XML_CATALOG_FILES'. When the public id is set the system id must also be set. + * @details \@abstract Sets the public id. This identifier should be in the default catalog in /etc/xml/catalog or in a path specified by the environment variable XML_CATALOG_FILES. When the public id is set the system id must also be set. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_public_id(const std::string& value) const; /** * @brief Returns the `systemID` property of `NSXMLDTD`. - * @details Returns the receiver's system identifier. This should be a URL that points to a valid DTD. + * @details \@abstract Sets the system id. This should be a URL that points to a valid DTD. * @return The converted Objective-C result. */ std::string system_id() const; /** * @brief Sets the `systemID` property of `NSXMLDTD`. - * @details Returns the receiver's system identifier. This should be a URL that points to a valid DTD. + * @details \@abstract Sets the system id. This should be a URL that points to a valid DTD. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_system_id(const std::string& value) const; diff --git a/include/generated/xmldtd_node.h b/include/generated/xmldtd_node.h index 229589e3..b79ae7b9 100644 --- a/include/generated/xmldtd_node.h +++ b/include/generated/xmldtd_node.h @@ -10,7 +10,7 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSXMLDTDNode` (Foundation). - * @details The nodes that are exclusive to a DTD. Every DTD node has a name. Object value is defined as follows: - Entity declaration - the string that that entity resolves to eg '\<' - Attribute declaration - the default value, if any - Element declaration - the validation string - Notation declaration - no objectValue + * @details \@class NSXMLDTDNode \@abstract The nodes that are exclusive to a DTD \@discussion Every DTD node has a name. Object value is defined as follows:\
    \
  • \Entity declaration\ - the string that that entity resolves to eg "<"\
  • \
  • \Attribute declaration\ - the default value, if any\
  • \
  • \Element declaration\ - the validation string\
  • \
  • \Notation declaration\ - no objectValue\
  • \
* Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref XMLNode. * @@ -50,55 +50,55 @@ namespace cocoon explicit XMLDTDNode(Adopt adopt); /** * @brief Returns the `DTDKind` property of `NSXMLDTDNode`. - * @details Returns the receiver's DTD kind. The DTD kind is distinct from a 'NSXMLDTDNode' object's node kind (returned by the 'NSXMLNode' ''XMLNode/kind'' method). + * @details \@abstract Sets the DTD sub kind. * @return The converted Objective-C result. */ XMLDTDNodeKind dtd_kind() const; /** * @brief Sets the `DTDKind` property of `NSXMLDTDNode`. - * @details Returns the receiver's DTD kind. The DTD kind is distinct from a 'NSXMLDTDNode' object's node kind (returned by the 'NSXMLNode' ''XMLNode/kind'' method). + * @details \@abstract Sets the DTD sub kind. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_dtd_kind(XMLDTDNodeKind value) const; /** * @brief Returns the `external` property of `NSXMLDTDNode`. - * @details True if the system id is set. Valid for entities and notations. + * @details \@abstract True if the system id is set. Valid for entities and notations. * @return The converted Objective-C result. */ bool is_external() const; /** * @brief Returns the `notationName` property of `NSXMLDTDNode`. - * @details Returns the name of the notation associated with the receiver. Notations are applicable to unparsed external entities, processing instructions, and some attribute values. + * @details \@abstract Set the notation name. Valid for entities only. * @return The converted Objective-C result. */ std::string notation_name() const; /** * @brief Sets the `notationName` property of `NSXMLDTDNode`. - * @details Returns the name of the notation associated with the receiver. Notations are applicable to unparsed external entities, processing instructions, and some attribute values. + * @details \@abstract Set the notation name. Valid for entities only. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_notation_name(const std::string& value) const; /** * @brief Returns the `publicID` property of `NSXMLDTDNode`. - * @details Returns the public identifier associated with the receiver. The public ID is applicable to entities and notations. This identifier should be in the default catalog in '/etc/xml/catalog' or in a path specified by the environment variable 'XML_CATALOG_FILES'. When the public id is set the system id must also be set. + * @details \@abstract Sets the public id. This identifier should be in the default catalog in /etc/xml/catalog or in a path specified by the environment variable XML_CATALOG_FILES. When the public id is set the system id must also be set. Valid for entities and notations. * @return The converted Objective-C result. */ std::string public_id() const; /** * @brief Sets the `publicID` property of `NSXMLDTDNode`. - * @details Returns the public identifier associated with the receiver. The public ID is applicable to entities and notations. This identifier should be in the default catalog in '/etc/xml/catalog' or in a path specified by the environment variable 'XML_CATALOG_FILES'. When the public id is set the system id must also be set. + * @details \@abstract Sets the public id. This identifier should be in the default catalog in /etc/xml/catalog or in a path specified by the environment variable XML_CATALOG_FILES. When the public id is set the system id must also be set. Valid for entities and notations. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_public_id(const std::string& value) const; /** * @brief Returns the `systemID` property of `NSXMLDTDNode`. - * @details Returns the system identifier associated with the receiver. This should be a URL that points to a valid DTD. Valid for entities and notations. + * @details \@abstract Sets the system id. This should be a URL that points to a valid DTD. Valid for entities and notations. * @return The converted Objective-C result. */ std::string system_id() const; /** * @brief Sets the `systemID` property of `NSXMLDTDNode`. - * @details Returns the system identifier associated with the receiver. This should be a URL that points to a valid DTD. Valid for entities and notations. + * @details \@abstract Sets the system id. This should be a URL that points to a valid DTD. Valid for entities and notations. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_system_id(const std::string& value) const; diff --git a/include/generated/xpc_coder.h b/include/generated/xpc_coder.h index e77891c2..ed7e1807 100644 --- a/include/generated/xpc_coder.h +++ b/include/generated/xpc_coder.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXPCCoder` (Foundation). - * @details A coder that encodes and decodes objects that your app sends over an XPC connection. If you want to perform custom encoding or decoding of \ objects that your app sends over an ''NSXPCConnection'', use \ to determine if the coder provided to your object is a kind of ''NSXPCCoder''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * Inherits from @ref Coder. * @@ -36,7 +35,6 @@ namespace cocoon explicit XPCCoder(Adopt adopt); /** * @brief Calls `-[NSXPCCoder decodeXPCObjectOfType:forKey:]`. - * @details Decodes an XPC object of the given type for the given key. This validates the type of the decoded object matches the type passed in. If they do not match, an exception is thrown (just like the rest of Secure Coding behaves). Note that this can return 'NULL', but calling an XPC function with 'NULL' will crash. * @param type Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. @@ -44,26 +42,22 @@ namespace cocoon Object decode_xpc_object_of_type(const xpc_type_t& type, const std::string& key) const; /** * @brief Calls `-[NSXPCCoder encodeXPCObject:forKey:]`. - * @details Encodes an XPC object and associates it with the given key. * @param xpc_object Argument converted to the Objective-C parameter of the same role. * @param key Argument converted to the Objective-C parameter of the same role. */ void encode_xpc_object(const Object& xpc_object, const std::string& key) const; /** * @brief Returns the `connection` property of `NSXPCCoder`. - * @details The current 'NSXPCConnection' that is encoding or decoding. * @return The converted Objective-C result. */ XPCConnection connection() const; /** * @brief Returns the `userInfo` property of `NSXPCCoder`. - * @details User-defined information associated with this coder. * @return The converted Objective-C result. */ Object user_info() const; /** * @brief Sets the `userInfo` property of `NSXPCCoder`. - * @details User-defined information associated with this coder. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_user_info(const Object& value) const; diff --git a/include/generated/xpc_connection.h b/include/generated/xpc_connection.h index da33e62a..27596201 100644 --- a/include/generated/xpc_connection.h +++ b/include/generated/xpc_connection.h @@ -14,7 +14,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXPCConnection` (Foundation). - * @details A bidirectional communication channel between two processes. This class is the primary means of creating and configuring the communication mechanism between two processes. Each process has one instance of this class to represent the endpoint in the communication channel. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -57,35 +56,29 @@ namespace cocoon explicit XPCConnection(Adopt adopt); /** * @brief Calls `-[NSXPCConnection activate]`. - * @details Activates the connection. Connections start in an inactive state. You must call 'activate' on a connection before it will send or receive any messages. Calling 'activate' on an active connection has no effect. For new code, using 'activate' is preferred over 'resume'. */ void activate() const; /** * @brief Calls `+[NSXPCConnection currentConnection]`. - * @details Returns the current connection, in the context of a call to a method on your exported object. Useful for determining 'who called this'. * @return The converted Objective-C result. */ static XPCConnection current_connection(); /** * @brief Calls `-[NSXPCConnection invalidate]`. - * @details Invalidates the connection. All outstanding error handling blocks and invalidation blocks will be called on the message handling queue. The connection must be invalidated before it is deallocated. After a connection is invalidated, no more messages may be sent or received. */ void invalidate() const; /** * @brief Calls `-[NSXPCConnection remoteObjectProxyWithErrorHandler:]`. - * @details Returns a proxy for the remote object, with an error handler. * @param handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object remote_object_proxy_with_error_handler(std::function handler) const; /** * @brief Calls `-[NSXPCConnection resume]`. - * @details Resumes the connection. All connections start suspended. You must resume them before they will start processing received messages or sending messages through the 'remoteObjectProxy'. Calling resume does not immediately launch the XPC service. The service will be started on demand when the first message is sent. However, if the name specified when creating the connection is determined to be invalid, your invalidation handler will be called immediately (and asynchronously) after calling resume. For new code, calling 'activate' is preferred for the initial activation of the connection. */ void resume() const; /** * @brief Calls `-[NSXPCConnection scheduleSendBarrierBlock:]`. - * @details Adds a barrier block to be executed on the connection after any outstanding sends have completed. This does not guarantee that messages will be received by the remote process by the time the block is invoked. If you need to ensure receipt of a message by the remote process, waiting for a reply to come back is the best option. * @param block Argument converted to the Objective-C parameter of the same role. */ void schedule_send_barrier_block(std::function block) const; @@ -97,115 +90,96 @@ namespace cocoon void set_code_signing_requirement(const std::string& requirement) const; /** * @brief Calls `-[NSXPCConnection suspend]`. - * @details Suspends the connection. Suspends must be balanced with resumes before the connection may be invalidated. */ void suspend() const; /** * @brief Calls `-[NSXPCConnection synchronousRemoteObjectProxyWithErrorHandler:]`. - * @details Returns a proxy that makes a synchronous IPC call instead of the default async behavior. The error handler block and reply block will be invoked on the calling thread before the message to the proxy returns, instead of on the queue for the connection. * @param handler Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ Object synchronous_remote_object_proxy_with_error_handler(std::function handler) const; /** * @brief Returns the `auditSessionIdentifier` property of `NSXPCConnection`. - * @details The audit session identifier of the connecting process. * @return The converted Objective-C result. */ int audit_session_identifier() const; /** * @brief Returns the `effectiveGroupIdentifier` property of `NSXPCConnection`. - * @details The effective group identifier (EGID) of the connecting process. * @return The converted Objective-C result. */ unsigned int effective_group_identifier() const; /** * @brief Returns the `effectiveUserIdentifier` property of `NSXPCConnection`. - * @details The effective user identifier (EUID) of the connecting process. * @return The converted Objective-C result. */ unsigned int effective_user_identifier() const; /** * @brief Returns the `endpoint` property of `NSXPCConnection`. - * @details The endpoint that was provided when the connection was initialized. * @return The converted Objective-C result. */ XPCListenerEndpoint endpoint() const; /** * @brief Returns the `exportedInterface` property of `NSXPCConnection`. - * @details The interface that describes messages that are allowed to be received by the exported object on this connection. This value is required if an exported object is set. * @return The converted Objective-C result. */ XPCInterface exported_interface() const; /** * @brief Sets the `exportedInterface` property of `NSXPCConnection`. - * @details The interface that describes messages that are allowed to be received by the exported object on this connection. This value is required if an exported object is set. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_exported_interface(const XPCInterface& value) const; /** * @brief Returns the `exportedObject` property of `NSXPCConnection`. - * @details An object that is vended to the other side of this connection. Messages sent to the 'remoteObjectProxy' from the other side of the connection will be dispatched to this object. Messages delivered to exported objects are serialized and sent on a non-main queue. The receiver is responsible for handling the messages on a different queue or thread if it is required. * @return The converted Objective-C result. */ Object exported_object() const; /** * @brief Sets the `exportedObject` property of `NSXPCConnection`. - * @details An object that is vended to the other side of this connection. Messages sent to the 'remoteObjectProxy' from the other side of the connection will be dispatched to this object. Messages delivered to exported objects are serialized and sent on a non-main queue. The receiver is responsible for handling the messages on a different queue or thread if it is required. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_exported_object(const Object& value) const; /** * @brief Returns the `interruptionHandler` property of `NSXPCConnection`. - * @details A block that is called if the remote process exits or crashes. It may be possible to re-establish the connection by simply sending another message. The handler will be invoked on the same queue as replies and other handlers, but there is no guarantee of ordering between those callbacks and this one. The 'interruptionHandler' property is cleared after the connection becomes invalid to mitigate the impact of a retain cycle created by referencing the 'NSXPCConnection' instance inside this block. * @return The converted Objective-C result. */ std::function interruption_handler() const; /** * @brief Sets the `interruptionHandler` property of `NSXPCConnection`. - * @details A block that is called if the remote process exits or crashes. It may be possible to re-establish the connection by simply sending another message. The handler will be invoked on the same queue as replies and other handlers, but there is no guarantee of ordering between those callbacks and this one. The 'interruptionHandler' property is cleared after the connection becomes invalid to mitigate the impact of a retain cycle created by referencing the 'NSXPCConnection' instance inside this block. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_interruption_handler(std::function value) const; /** * @brief Returns the `invalidationHandler` property of `NSXPCConnection`. - * @details A block that is called if the connection can not be formed or has terminated and may not be re-established. The invalidation handler will also be called if a connection created with an 'NSXPCListenerEndpoint' is invalidated from the remote side, or if the 'NSXPCListener' used to create that endpoint is invalidated. You may not send messages over the connection from within an invalidation handler block. The 'invalidationHandler' property is cleared after the connection becomes invalid to mitigate the impact of a retain cycle created by referencing the 'NSXPCConnection' instance inside this block. * @return The converted Objective-C result. */ std::function invalidation_handler() const; /** * @brief Sets the `invalidationHandler` property of `NSXPCConnection`. - * @details A block that is called if the connection can not be formed or has terminated and may not be re-established. The invalidation handler will also be called if a connection created with an 'NSXPCListenerEndpoint' is invalidated from the remote side, or if the 'NSXPCListener' used to create that endpoint is invalidated. You may not send messages over the connection from within an invalidation handler block. The 'invalidationHandler' property is cleared after the connection becomes invalid to mitigate the impact of a retain cycle created by referencing the 'NSXPCConnection' instance inside this block. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_invalidation_handler(std::function value) const; /** * @brief Returns the `processIdentifier` property of `NSXPCConnection`. - * @details The process identifier (PID) of the connecting process. * @return The converted Objective-C result. */ int process_identifier() const; /** * @brief Returns the `remoteObjectInterface` property of `NSXPCConnection`. - * @details The interface that describes messages that are allowed to be received by the remote object on the other side of this connection. This value is required if messages are sent over this connection. * @return The converted Objective-C result. */ XPCInterface remote_object_interface() const; /** * @brief Sets the `remoteObjectInterface` property of `NSXPCConnection`. - * @details The interface that describes messages that are allowed to be received by the remote object on the other side of this connection. This value is required if messages are sent over this connection. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_remote_object_interface(const XPCInterface& value) const; /** * @brief Returns the `remoteObjectProxy` property of `NSXPCConnection`. - * @details Returns a proxy for the remote object (that is, the object exported from the other side of this connection). * @return The converted Objective-C result. */ Object remote_object_proxy() const; /** * @brief Returns the `serviceName` property of `NSXPCConnection`. - * @details The name of the XPC service that this connection was configured to connect to. * @return The converted Objective-C result. */ std::string service_name() const; diff --git a/include/generated/xpc_interface.h b/include/generated/xpc_interface.h index 2502a6c3..706c4dbf 100644 --- a/include/generated/xpc_interface.h +++ b/include/generated/xpc_interface.h @@ -12,7 +12,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXPCInterface` (Foundation). - * @details An interface that may be sent to an exported object or remote object proxy. This object holds all information about the interface of an exported object or remote object proxy. It describes what messages are allowed, what kinds of objects are allowed as arguments, what the signature of any reply blocks are, and information about additional proxy objects. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -51,7 +50,6 @@ namespace cocoon xpc_type_t xpc_type_for_selector(const std::string& sel, std::uint64_t arg, bool of_reply) const; /** * @brief Calls `-[NSXPCInterface classesForSelector:argumentIndex:ofReply:]`. - * @details Returns the expected classes for a collection parameter in a method of the protocol. * @param sel Argument converted to the Objective-C parameter of the same role. * @param arg Argument converted to the Objective-C parameter of the same role. * @param of_reply Argument converted to the Objective-C parameter of the same role. @@ -60,7 +58,6 @@ namespace cocoon std::vector classes_for_selector(const std::string& sel, std::uint64_t arg, bool of_reply) const; /** * @brief Calls `-[NSXPCInterface interfaceForSelector:argumentIndex:ofReply:]`. - * @details Returns the interface previously configured for a proxy argument. * @param sel Argument converted to the Objective-C parameter of the same role. * @param arg Argument converted to the Objective-C parameter of the same role. * @param of_reply Argument converted to the Objective-C parameter of the same role. @@ -69,14 +66,12 @@ namespace cocoon XPCInterface interface_for_selector(const std::string& sel, std::uint64_t arg, bool of_reply) const; /** * @brief Calls `+[NSXPCInterface interfaceWithProtocol:]`. - * @details Returns an 'NSXPCInterface' instance for a given protocol. Most interfaces do not need any further configuration. Interfaces with collection classes or additional proxy objects should be configured using the methods below. * @param protocol Argument converted to the Objective-C parameter of the same role. * @return The converted Objective-C result. */ static XPCInterface interface_with_protocol(const Object& protocol); /** * @brief Calls `-[NSXPCInterface setClasses:forSelector:argumentIndex:ofReply:]`. - * @details Configures the expected classes for a collection parameter in a method of the protocol. If an argument to a method in your protocol is a collection class (for example, 'NSArray' or 'NSDictionary'), then the interface must be configured with the set of expected classes contained inside of the collection. The 'classes' argument should be an 'NSSet' containing 'Class' objects. The 'sel' argument specifies which method in the protocol is being configured. The 'arg' parameter specifies which argument of the method the 'NSSet' applies to. If the 'NSSet' is for an argument of the reply block in the method, pass 'YES' for 'ofReply'. The first argument is index 0 for both the method and the reply block. If the expected classes are all property list types, calling this method is optional. * @param classes Argument converted to the Objective-C parameter of the same role. * @param sel Argument converted to the Objective-C parameter of the same role. * @param arg Argument converted to the Objective-C parameter of the same role. @@ -85,7 +80,6 @@ namespace cocoon void set_classes(const std::vector& classes, const std::string& sel, std::uint64_t arg, bool of_reply) const; /** * @brief Calls `-[NSXPCInterface setInterface:forSelector:argumentIndex:ofReply:]`. - * @details Configures an argument in a method of the protocol to be sent as a proxy object instead of by copy. * @param ifc Argument converted to the Objective-C parameter of the same role. * @param sel Argument converted to the Objective-C parameter of the same role. * @param arg Argument converted to the Objective-C parameter of the same role. @@ -102,13 +96,11 @@ namespace cocoon void set_xpc_type(const xpc_type_t& type, const std::string& sel, std::uint64_t arg, bool of_reply) const; /** * @brief Returns the `protocol` property of `NSXPCInterface`. - * @details The Objective-C protocol this 'NSXPCInterface' is based upon. * @return The converted Objective-C result. */ Object protocol() const; /** * @brief Sets the `protocol` property of `NSXPCInterface`. - * @details The Objective-C protocol this 'NSXPCInterface' is based upon. * @param value Argument converted to the Objective-C parameter of the same role. */ void set_protocol(const Object& value) const; diff --git a/include/generated/xpc_listener.h b/include/generated/xpc_listener.h index 7d2e7be9..63232d24 100644 --- a/include/generated/xpc_listener.h +++ b/include/generated/xpc_listener.h @@ -13,7 +13,6 @@ namespace cocoon /** * @brief C++ handle for the Objective-C class `NSXPCListener` (Foundation). - * @details A listener that waits for new incoming connections, configures them, and accepts or rejects them. Each XPC service, launchd agent, or launchd daemon typically has at least one ''NSXPCListener'' object that listens for connections to a specified service name. Each listener must have a delegate that conforms to the ''NSXPCListenerDelegate'' protocol. When the listener receives a new connection request, it creates a new ''NSXPCConnection'' object, then asks the delegate to inspect, configure, and resume the connection object by calling the delegate's ''NSXPCListenerDelegate/listener(:shouldAcceptNewConnection:)'' method. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example @@ -48,28 +47,23 @@ namespace cocoon explicit XPCListener(Adopt adopt); /** * @brief Calls `-[NSXPCListener activate]`. - * @details Activates the listener. Listeners start in an inactive state. You must call 'activate' on a listener before it will send or receive any messages. Calling 'activate' on an active listener has no effect. For new code, using 'activate' is preferred over 'resume'. */ void activate() const; /** * @brief Calls `+[NSXPCListener anonymousListener]`. - * @details Creates an anonymous listener connection. Other processes may connect to this listener by passing this listener object's endpoint to 'NSXPCConnection''s 'initWithListenerEndpoint:' method. * @return The converted Objective-C result. */ static XPCListener anonymous_listener(); /** * @brief Calls `-[NSXPCListener invalidate]`. - * @details Invalidates the listener. No more connections will be created. Once a listener is invalidated it may not be resumed or suspended. */ void invalidate() const; /** * @brief Calls `-[NSXPCListener resume]`. - * @details Resumes the listener. All listeners start suspended and must be resumed before they will process incoming requests. If called on the 'serviceListener', this method will never return. Call it as the last step inside your 'main' function in your XPC service. If called on any other 'NSXPCListener', the listener is resumed and the method returns immediately. For new code, calling 'activate' is preferred for the initial activation of the listener. */ void resume() const; /** * @brief Calls `+[NSXPCListener serviceListener]`. - * @details Returns the singleton listener for an XPC service. If your listener is an XPC service (that is, in the XPCServices folder of an application or framework), then use this method to get the shared, singleton 'NSXPCListener' object that will await new connections. When the resume method is called on this listener, it will not return. Instead it hands over control to the object and allows it to service the listener as appropriate. This makes it ideal for use in your 'main()' function. * @return The converted Objective-C result. */ static XPCListener service_listener(); @@ -81,12 +75,10 @@ namespace cocoon void set_connection_code_signing_requirement(const std::string& requirement) const; /** * @brief Calls `-[NSXPCListener suspend]`. - * @details Suspends the listener. Suspends must be balanced with resumes before the listener may be invalidated. */ void suspend() const; /** * @brief Returns the `endpoint` property of `NSXPCListener`. - * @details An endpoint object which may be sent over an existing connection. This allows the receiver of the endpoint to create a new connection to this 'NSXPCListener'. The 'NSXPCListenerEndpoint' uniquely names this listener object across connections. * @return The converted Objective-C result. */ XPCListenerEndpoint endpoint() const; diff --git a/include/generated/xpc_listener_endpoint.h b/include/generated/xpc_listener_endpoint.h index abc2021e..dcbdb363 100644 --- a/include/generated/xpc_listener_endpoint.h +++ b/include/generated/xpc_listener_endpoint.h @@ -10,7 +10,6 @@ namespace cocoon { /** * @brief C++ handle for the Objective-C class `NSXPCListenerEndpoint` (Foundation). - * @details An object that names a specific XPC listener. An instance of ''NSXPCListenerEndpoint'' may be retrieved from an ''NSXPCListener'' instance and sent over existing ''NSXPCConnection''s. A process may then use the endpoint to create a new ''NSXPCConnection'' to the original ''NSXPCListener''. This pattern is useful if you have a service which multiplexes work to other services. The service can act as an intermediate helper. The requesting application does not need to know specifically which service it is connecting to, just that it implements a known ''NSXPCInterface''. * Handles are cheap, copyable wrappers around a retained native object: copies refer to the same underlying instance. * * @par Example diff --git a/src/generated/application.mm b/src/generated/application.mm index 6fe47a1c..48cadc9e 100644 --- a/src/generated/application.mm +++ b/src/generated/application.mm @@ -284,9 +284,9 @@ - (BOOL)application:(NSApplication*)application continueUserActivity:(NSUserActi { return {}; } - return [blk](std::vector a281_0) -> void + return [blk](std::vector a278_0) -> void { - blk(cocoon::internal::to_array(a281_0, [](const cocoon::Object& e) -> id + blk(cocoon::internal::to_array(a278_0, [](const cocoon::Object& e) -> id { return cocoon::internal::native_id(e); })); diff --git a/src/generated/browser.mm b/src/generated/browser.mm index 8404b9df..fedb63a8 100644 --- a/src/generated/browser.mm +++ b/src/generated/browser.mm @@ -235,46 +235,6 @@ - (BOOL)browser:(NSBrowser*)browser shouldShowCellExpansionForRow:(NSInteger)row return static_cast<::BOOL>(__r); } -#ifdef COCOON_MACOS_27 -- (id)browser:(NSBrowser*)browser pasteboardWriterForRow:(NSInteger)row column:(NSInteger)column -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "pasteboard_writer_for_row_column", static_cast(row), static_cast(column)); - return cocoon::internal::native_id(__r); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (void)browser:(NSBrowser*)browser draggingSession:(NSDraggingSession*)session willBeginAtPoint:(NSPoint)screenPoint forRowsWithIndexes:(NSIndexSet*)rowIndexes column:(NSInteger)column -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "dragging_session_will_begin_at_point_for_rows_with_indexes_column", cocoon::internal::wrap(session), cocoon::internal::from(screenPoint), cocoon::internal::wrap(rowIndexes), static_cast(column)); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (void)browser:(NSBrowser*)browser draggingSession:(NSDraggingSession*)session endedAtPoint:(NSPoint)screenPoint operation:(NSDragOperation)operation -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "dragging_session_ended_at_point_operation", cocoon::internal::wrap(session), cocoon::internal::from(screenPoint), static_cast(operation)); -} - -#endif - - (BOOL)browser:(NSBrowser*)browser writeRowsWithIndexes:(NSIndexSet*)rowIndexes inColumn:(NSInteger)column toPasteboard:(NSPasteboard*)pasteboard { id strongHost = host; @@ -493,27 +453,6 @@ - (BOOL)respondsToSelector:(SEL)selector { return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "should_show_cell_expansion_for_row_column"); } -#ifdef COCOON_MACOS_27 - if (selector == @selector(browser:pasteboardWriterForRow:column:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "pasteboard_writer_for_row_column"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(browser:draggingSession:willBeginAtPoint:forRowsWithIndexes:column:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "dragging_session_will_begin_at_point_for_rows_with_indexes_column"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(browser:draggingSession:endedAtPoint:operation:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "dragging_session_ended_at_point_operation"); - } -#endif - if (selector == @selector(browser:writeRowsWithIndexes:inColumn:toPasteboard:)) { return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "write_rows_with_indexes_in_column_to_pasteboard"); diff --git a/src/generated/constants.mm b/src/generated/constants.mm index 202efcca..effbed76 100644 --- a/src/generated/constants.mm +++ b/src/generated/constants.mm @@ -3800,10 +3800,6 @@ { return cocoon::internal::from(cocoon::internal::load_symbol("NSCocoaVersionDocumentAttribute", nil)); } - std::string AttributedStringDocumentAttributeKey::paper_margin_document_attribute() - { - return cocoon::internal::from(cocoon::internal::load_symbol("NSPaperMarginDocumentAttribute", nil)); - } std::string AttributedStringDocumentAttributeKey::converted_document_attribute() { return cocoon::internal::from(cocoon::internal::load_symbol("NSConvertedDocumentAttribute", nil)); @@ -6467,14 +6463,6 @@ { return cocoon::internal::from(cocoon::internal::load_symbol("NSTextCheckingGenerateInlinePredictionsKey", nil)); } - std::string TextCheckingOptionKey::text_checking_automatic_capitalization_enabled_key() - { - return cocoon::internal::from(cocoon::internal::load_symbol("NSTextCheckingAutomaticCapitalizationEnabledKey", nil)); - } - std::string TextCheckingOptionKey::text_checking_wait_for_all_grammar_checking_results_key() - { - return cocoon::internal::from(cocoon::internal::load_symbol("NSTextCheckingWaitForAllGrammarCheckingResultsKey", nil)); - } std::string TextContentType::username() { diff --git a/src/generated/control.mm b/src/generated/control.mm index e524caca..19afbeec 100644 --- a/src/generated/control.mm +++ b/src/generated/control.mm @@ -24,17 +24,6 @@ return static_cast([cocoon::internal::ns<::NSControl>(this) abortEditing]); } -#ifdef COCOON_MACOS_27 - void Control::add_target(const Object& target, const std::string& action, ControlEvents control_events) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSControl>(this) addTarget:cocoon::internal::native_id(target) action:NSSelectorFromString(cocoon::internal::to(action)) forControlEvents:static_cast<::NSControlEvents>(control_events)]; - } - } - -#endif - Text Control::current_editor() const { return cocoon::internal::wrap([cocoon::internal::ns<::NSControl>(this) currentEditor]); @@ -80,17 +69,6 @@ [cocoon::internal::ns<::NSControl>(this) performClick:cocoon::internal::native_id(sender)]; } -#ifdef COCOON_MACOS_27 - void Control::remove_target(const Object& target, const std::string& action, ControlEvents control_events) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSControl>(this) removeTarget:cocoon::internal::native_id(target) action:NSSelectorFromString(cocoon::internal::to(action)) forControlEvents:static_cast<::NSControlEvents>(control_events)]; - } - } - -#endif - void Control::select_cell(const Cell& cell) const { [cocoon::internal::ns<::NSControl>(this) selectCell:cocoon::internal::native<::NSCell>(cell)]; diff --git a/src/generated/event.mm b/src/generated/event.mm index 2930dca0..c477e3af 100644 --- a/src/generated/event.mm +++ b/src/generated/event.mm @@ -375,18 +375,6 @@ return static_cast([cocoon::internal::ns<::NSEvent>(this) timestamp]); } -#ifdef COCOON_MACOS_27 - bool Event::is_touch_swipe_navigation_enabled() - { - if (@available(macOS 27.0, *)) - { - return static_cast([::NSEvent isTouchSwipeNavigationEnabled]); - } - return {}; - } - -#endif - TrackingArea Event::tracking_area() const { return cocoon::internal::wrap([cocoon::internal::ns<::NSEvent>(this) trackingArea]); diff --git a/src/generated/file_promise_provider.mm b/src/generated/file_promise_provider.mm index 5a1e13e4..fc15e99b 100644 --- a/src/generated/file_promise_provider.mm +++ b/src/generated/file_promise_provider.mm @@ -35,9 +35,9 @@ - (void)filePromiseProvider:(NSFilePromiseProvider*)filePromiseProvider writePro { return {}; } - return [blk](cocoon::Error a282_0) -> void + return [blk](cocoon::Error a279_0) -> void { - blk(cocoon::internal::native<::NSError>(a282_0)); + blk(cocoon::internal::native<::NSError>(a279_0)); }; }()); } diff --git a/src/generated/gesture_recognizer.mm b/src/generated/gesture_recognizer.mm index fd9d6aa4..c4a5aa66 100644 --- a/src/generated/gesture_recognizer.mm +++ b/src/generated/gesture_recognizer.mm @@ -283,29 +283,6 @@ - (BOOL)respondsToSelector:(SEL)selector [cocoon::internal::ns<::NSGestureRecognizer>(this) setAllowedTouchTypes:static_cast<::NSTouchTypeMask>(value)]; } -#ifdef COCOON_MACOS_27 - bool GestureRecognizer::is_cancellable_by_scroll_gesture() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSGestureRecognizer>(this) isCancellableByScrollGesture]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void GestureRecognizer::set_cancellable_by_scroll_gesture(bool value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSGestureRecognizer>(this) setCancellableByScrollGesture:static_cast<::BOOL>(value)]; - } - } - -#endif - bool GestureRecognizer::delays_key_events() const { return static_cast([cocoon::internal::ns<::NSGestureRecognizer>(this) delaysKeyEvents]); diff --git a/src/generated/glass_effect_view.mm b/src/generated/glass_effect_view.mm index 3b397db2..e112a743 100644 --- a/src/generated/glass_effect_view.mm +++ b/src/generated/glass_effect_view.mm @@ -35,29 +35,6 @@ [cocoon::internal::ns<::NSGlassEffectView>(this) setCornerRadius:static_cast<::CGFloat>(value)]; } -#ifdef COCOON_MACOS_27 - bool GlassEffectView::effect_is_interactive() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSGlassEffectView>(this) effectIsInteractive]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void GlassEffectView::set_effect_is_interactive(bool value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSGlassEffectView>(this) setEffectIsInteractive:static_cast<::BOOL>(value)]; - } - } - -#endif - GlassStyle GlassEffectView::style() const { return static_cast([cocoon::internal::ns<::NSGlassEffectView>(this) style]); diff --git a/src/generated/menu_item.mm b/src/generated/menu_item.mm index 4e2d78b5..1c051155 100644 --- a/src/generated/menu_item.mm +++ b/src/generated/menu_item.mm @@ -211,29 +211,6 @@ return cocoon::internal::wrap([cocoon::internal::ns<::NSMenuItem>(this) parentItem]); } -#ifdef COCOON_MACOS_27 - MenuItemImageVisibility MenuItem::preferred_image_visibility() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSMenuItem>(this) preferredImageVisibility]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void MenuItem::set_preferred_image_visibility(MenuItemImageVisibility value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSMenuItem>(this) setPreferredImageVisibility:static_cast<::NSMenuItemImageVisibility>(value)]; - } - } - -#endif - Object MenuItem::represented_object() const { return cocoon::internal::wrap([cocoon::internal::ns<::NSMenuItem>(this) representedObject]); diff --git a/src/generated/mutable_paragraph_style.mm b/src/generated/mutable_paragraph_style.mm index d233947a..8b87c01d 100644 --- a/src/generated/mutable_paragraph_style.mm +++ b/src/generated/mutable_paragraph_style.mm @@ -30,16 +30,6 @@ [cocoon::internal::ns<::NSMutableParagraphStyle>(this) setParagraphStyle:cocoon::internal::native<::NSParagraphStyle>(obj)]; } - TextAlignment MutableParagraphStyle::alignment() const - { - return static_cast([cocoon::internal::ns<::NSMutableParagraphStyle>(this) alignment]); - } - - void MutableParagraphStyle::set_alignment(TextAlignment value) const - { - [cocoon::internal::ns<::NSMutableParagraphStyle>(this) setAlignment:static_cast<::NSTextAlignment>(value)]; - } - bool MutableParagraphStyle::allows_default_tightening_for_truncation() const { return static_cast([cocoon::internal::ns<::NSMutableParagraphStyle>(this) allowsDefaultTighteningForTruncation]); @@ -90,16 +80,6 @@ [cocoon::internal::ns<::NSMutableParagraphStyle>(this) setHeadIndent:static_cast<::CGFloat>(value)]; } - std::int64_t MutableParagraphStyle::header_level() const - { - return static_cast([cocoon::internal::ns<::NSMutableParagraphStyle>(this) headerLevel]); - } - - void MutableParagraphStyle::set_header_level(std::int64_t value) const - { - [cocoon::internal::ns<::NSMutableParagraphStyle>(this) setHeaderLevel:static_cast<::NSInteger>(value)]; - } - float MutableParagraphStyle::hyphenation_factor() const { return static_cast([cocoon::internal::ns<::NSMutableParagraphStyle>(this) hyphenationFactor]); @@ -216,22 +196,6 @@ [cocoon::internal::ns<::NSMutableParagraphStyle>(this) setTailIndent:static_cast<::CGFloat>(value)]; } - std::vector MutableParagraphStyle::text_blocks() const - { - return cocoon::internal::from_array([cocoon::internal::ns<::NSMutableParagraphStyle>(this) textBlocks], [](id e) -> TextBlock - { - return cocoon::internal::wrap((::NSTextBlock*)e); - }); - } - - void MutableParagraphStyle::set_text_blocks(const std::vector& value) const - { - [cocoon::internal::ns<::NSMutableParagraphStyle>(this) setTextBlocks:cocoon::internal::to_array(value, [](const TextBlock& e) -> id - { - return cocoon::internal::native<::NSTextBlock>(e); - })]; - } - std::vector MutableParagraphStyle::text_lists() const { return cocoon::internal::from_array([cocoon::internal::ns<::NSMutableParagraphStyle>(this) textLists], [](id e) -> TextList @@ -248,16 +212,6 @@ })]; } - float MutableParagraphStyle::tightening_factor_for_truncation() const - { - return static_cast([cocoon::internal::ns<::NSMutableParagraphStyle>(this) tighteningFactorForTruncation]); - } - - void MutableParagraphStyle::set_tightening_factor_for_truncation(float value) const - { - [cocoon::internal::ns<::NSMutableParagraphStyle>(this) setTighteningFactorForTruncation:static_cast(value)]; - } - bool MutableParagraphStyle::uses_default_hyphenation() const { return static_cast([cocoon::internal::ns<::NSMutableParagraphStyle>(this) usesDefaultHyphenation]); diff --git a/src/generated/pan_gesture_recognizer.mm b/src/generated/pan_gesture_recognizer.mm index 12f19eb0..5dfc6bb1 100644 --- a/src/generated/pan_gesture_recognizer.mm +++ b/src/generated/pan_gesture_recognizer.mm @@ -41,52 +41,6 @@ [cocoon::internal::ns<::NSPanGestureRecognizer>(this) setButtonMask:static_cast<::NSUInteger>(value)]; } -#ifdef COCOON_MACOS_27 - std::int64_t PanGestureRecognizer::maximum_number_of_touches() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSPanGestureRecognizer>(this) maximumNumberOfTouches]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void PanGestureRecognizer::set_maximum_number_of_touches(std::int64_t value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSPanGestureRecognizer>(this) setMaximumNumberOfTouches:static_cast<::NSInteger>(value)]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - std::int64_t PanGestureRecognizer::minimum_number_of_touches() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSPanGestureRecognizer>(this) minimumNumberOfTouches]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void PanGestureRecognizer::set_minimum_number_of_touches(std::int64_t value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSPanGestureRecognizer>(this) setMinimumNumberOfTouches:static_cast<::NSInteger>(value)]; - } - } - -#endif - std::int64_t PanGestureRecognizer::number_of_touches_required() const { return static_cast([cocoon::internal::ns<::NSPanGestureRecognizer>(this) numberOfTouchesRequired]); diff --git a/src/generated/paragraph_style.mm b/src/generated/paragraph_style.mm index b53e4629..d1fe17ff 100644 --- a/src/generated/paragraph_style.mm +++ b/src/generated/paragraph_style.mm @@ -20,11 +20,6 @@ return static_cast([::NSParagraphStyle defaultWritingDirectionForLanguage:cocoon::internal::to(language_name)]); } - TextAlignment ParagraphStyle::alignment() const - { - return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) alignment]); - } - bool ParagraphStyle::allows_default_tightening_for_truncation() const { return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) allowsDefaultTighteningForTruncation]); @@ -55,11 +50,6 @@ return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) headIndent]); } - std::int64_t ParagraphStyle::header_level() const - { - return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) headerLevel]); - } - float ParagraphStyle::hyphenation_factor() const { return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) hyphenationFactor]); @@ -118,14 +108,6 @@ return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) tailIndent]); } - std::vector ParagraphStyle::text_blocks() const - { - return cocoon::internal::from_array([cocoon::internal::ns<::NSParagraphStyle>(this) textBlocks], [](id e) -> TextBlock - { - return cocoon::internal::wrap((::NSTextBlock*)e); - }); - } - std::vector ParagraphStyle::text_lists() const { return cocoon::internal::from_array([cocoon::internal::ns<::NSParagraphStyle>(this) textLists], [](id e) -> TextList @@ -134,11 +116,6 @@ }); } - float ParagraphStyle::tightening_factor_for_truncation() const - { - return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) tighteningFactorForTruncation]); - } - bool ParagraphStyle::uses_default_hyphenation() const { return static_cast([cocoon::internal::ns<::NSParagraphStyle>(this) usesDefaultHyphenation]); diff --git a/src/generated/refresh_controller.mm b/src/generated/refresh_controller.mm deleted file mode 100644 index 946298e2..00000000 --- a/src/generated/refresh_controller.mm +++ /dev/null @@ -1,146 +0,0 @@ -#include "generated/refresh_controller.h" -#include "internal.h" - -#ifdef COCOON_MACOS_27 -namespace cocoon -{ - RefreshController::RefreshController() : RefreshController(Adopt{cocoon::internal::retain([[::NSRefreshController alloc] init])}) - { - } - - RefreshController::RefreshController(std::nullptr_t) : Object(nullptr) - { - } - - RefreshController::RefreshController(Adopt adopt) : Object(adopt) - { - } - -#ifdef COCOON_MACOS_27 - void RefreshController::begin_refreshing() const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSRefreshController>(this) beginRefreshing]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - void RefreshController::end_refreshing() const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSRefreshController>(this) endRefreshing]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - std::string RefreshController::action() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::from(NSStringFromSelector([cocoon::internal::ns<::NSRefreshController>(this) action])); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void RefreshController::set_action(const std::string& value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSRefreshController>(this) setAction:NSSelectorFromString(cocoon::internal::to(value))]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - AttributedString RefreshController::attributed_title() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSRefreshController>(this) attributedTitle]); - } - return AttributedString(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - void RefreshController::set_attributed_title(const AttributedString& value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSRefreshController>(this) setAttributedTitle:cocoon::internal::native<::NSAttributedString>(value)]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - bool RefreshController::is_refreshing() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSRefreshController>(this) isRefreshing]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - Object RefreshController::target() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSRefreshController>(this) target]); - } - return Object(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - void RefreshController::set_target(const Object& value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSRefreshController>(this) setTarget:cocoon::internal::native_id(value)]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - Color RefreshController::tint_color() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSRefreshController>(this) tintColor]); - } - return Color(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - void RefreshController::set_tint_color(const Color& value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSRefreshController>(this) setTintColor:cocoon::internal::native<::NSColor>(value)]; - } - } - -#endif -} - -#endif diff --git a/src/generated/screen.mm b/src/generated/screen.mm index fe438b68..67376b01 100644 --- a/src/generated/screen.mm +++ b/src/generated/screen.mm @@ -125,18 +125,6 @@ return (const WindowDepth*)([cocoon::internal::ns<::NSScreen>(this) supportedWindowDepths]); } -#ifdef COCOON_MACOS_27 - ScreenTouchCapabilities Screen::touch_capabilities() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSScreen>(this) touchCapabilities]); - } - return {}; - } - -#endif - Rect Screen::visible_frame() const { return cocoon::internal::from([cocoon::internal::ns<::NSScreen>(this) visibleFrame]); diff --git a/src/generated/scroll_view.mm b/src/generated/scroll_view.mm index 1d110be3..6851467a 100644 --- a/src/generated/scroll_view.mm +++ b/src/generated/scroll_view.mm @@ -304,29 +304,6 @@ [cocoon::internal::ns<::NSScrollView>(this) setMaxMagnification:static_cast<::CGFloat>(value)]; } -#ifdef COCOON_MACOS_27 - std::int64_t ScrollView::maximum_number_of_touches_for_scrolling() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSScrollView>(this) maximumNumberOfTouchesForScrolling]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void ScrollView::set_maximum_number_of_touches_for_scrolling(std::int64_t value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSScrollView>(this) setMaximumNumberOfTouchesForScrolling:static_cast<::NSInteger>(value)]; - } - } - -#endif - double ScrollView::min_magnification() const { return static_cast([cocoon::internal::ns<::NSScrollView>(this) minMagnification]); @@ -337,29 +314,6 @@ [cocoon::internal::ns<::NSScrollView>(this) setMinMagnification:static_cast<::CGFloat>(value)]; } -#ifdef COCOON_MACOS_27 - std::int64_t ScrollView::minimum_number_of_touches_for_scrolling() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSScrollView>(this) minimumNumberOfTouchesForScrolling]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void ScrollView::set_minimum_number_of_touches_for_scrolling(std::int64_t value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSScrollView>(this) setMinimumNumberOfTouchesForScrolling:static_cast<::NSInteger>(value)]; - } - } - -#endif - double ScrollView::page_scroll() const { return static_cast([cocoon::internal::ns<::NSScrollView>(this) pageScroll]); @@ -370,29 +324,6 @@ [cocoon::internal::ns<::NSScrollView>(this) setPageScroll:static_cast<::CGFloat>(value)]; } -#ifdef COCOON_MACOS_27 - RefreshController ScrollView::refresh_controller() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSScrollView>(this) refreshController]); - } - return RefreshController(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - void ScrollView::set_refresh_controller(const RefreshController& value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSScrollView>(this) setRefreshController:cocoon::internal::native<::NSRefreshController>(value)]; - } - } - -#endif - std::string ScrollView::ruler_view_class() { return cocoon::internal::from(NSStringFromClass([::NSScrollView rulerViewClass])); @@ -413,18 +344,6 @@ [cocoon::internal::ns<::NSScrollView>(this) setRulersVisible:static_cast<::BOOL>(value)]; } -#ifdef COCOON_MACOS_27 - GestureRecognizer ScrollView::scroll_gesture_for_relationships() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSScrollView>(this) scrollGestureForRelationships]); - } - return GestureRecognizer(nullptr); - } - -#endif - Insets ScrollView::scroller_insets() const { return cocoon::internal::from([cocoon::internal::ns<::NSScrollView>(this) scrollerInsets]); @@ -465,29 +384,6 @@ [cocoon::internal::ns<::NSScrollView>(this) setScrollsDynamically:static_cast<::BOOL>(value)]; } -#ifdef COCOON_MACOS_27 - bool ScrollView::is_touch_scrolling_enabled() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSScrollView>(this) isTouchScrollingEnabled]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void ScrollView::set_touch_scrolling_enabled(bool value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSScrollView>(this) setTouchScrollingEnabled:static_cast<::BOOL>(value)]; - } - } - -#endif - bool ScrollView::uses_predominant_axis_scrolling() const { return static_cast([cocoon::internal::ns<::NSScrollView>(this) usesPredominantAxisScrolling]); diff --git a/src/generated/segmented_control.mm b/src/generated/segmented_control.mm index 6cf2a909..69d3e61d 100644 --- a/src/generated/segmented_control.mm +++ b/src/generated/segmented_control.mm @@ -194,29 +194,6 @@ return static_cast([cocoon::internal::ns<::NSSegmentedControl>(this) indexOfSelectedItem]); } -#ifdef COCOON_MACOS_27 - SegmentedControlRole SegmentedControl::role() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSSegmentedControl>(this) role]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void SegmentedControl::set_role(SegmentedControlRole value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSSegmentedControl>(this) setRole:static_cast<::NSSegmentedControlRole>(value)]; - } - } - -#endif - std::int64_t SegmentedControl::segment_count() const { return static_cast([cocoon::internal::ns<::NSSegmentedControl>(this) segmentCount]); diff --git a/src/generated/spell_checker.mm b/src/generated/spell_checker.mm index ef5f38fe..2a09f16a 100644 --- a/src/generated/spell_checker.mm +++ b/src/generated/spell_checker.mm @@ -113,17 +113,6 @@ return static_cast([cocoon::internal::ns<::NSSpellChecker>(this) hasLearnedWord:cocoon::internal::to(word)]); } -#ifdef COCOON_MACOS_27 - void SpellChecker::ignore_grammar_range(const Range& grammar_range, const std::string& sentence, std::int64_t tag) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSSpellChecker>(this) ignoreGrammarRange:cocoon::internal::to(grammar_range) inSentence:cocoon::internal::to(sentence) inSpellDocumentWithTag:static_cast<::NSInteger>(tag)]; - } - } - -#endif - void SpellChecker::ignore_word(const std::string& word_to_ignore, std::int64_t tag) const { [cocoon::internal::ns<::NSSpellChecker>(this) ignoreWord:cocoon::internal::to(word_to_ignore) inSpellDocumentWithTag:static_cast<::NSInteger>(tag)]; diff --git a/src/generated/status_item.mm b/src/generated/status_item.mm index eeb55b47..ad755d75 100644 --- a/src/generated/status_item.mm +++ b/src/generated/status_item.mm @@ -1,72 +1,10 @@ #include "generated/status_item.h" #include "internal.h" -#ifdef COCOON_MACOS_27 -@interface AKStatusItemExpandedInterfaceDelegateDelegate : NSObject -{ -@public - __weak id host; -} -@end - -@implementation AKStatusItemExpandedInterfaceDelegateDelegate - -#ifdef COCOON_MACOS_27 -- (void)statusItem:(NSStatusItem*)statusItem didBeginExpandedInterfaceSession:(NSStatusItemExpandedInterfaceSession*)expandedInterfaceSession -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "did_begin_expanded_interface_session", cocoon::internal::wrap(expandedInterfaceSession)); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (void)statusItemDidEndExpandedInterfaceSession:(NSStatusItem*)statusItem animated:(BOOL)animated -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "did_end_expanded_interface_session_animated", static_cast(animated)); -} - -#endif - -- (BOOL)respondsToSelector:(SEL)selector -{ - id strongHost = host; -#ifdef COCOON_MACOS_27 - if (selector == @selector(statusItem:didBeginExpandedInterfaceSession:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "did_begin_expanded_interface_session"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(statusItemDidEndExpandedInterfaceSession:animated:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "did_end_expanded_interface_session_animated"); - } -#endif - - return [super respondsToSelector:selector]; -} - -@end - -#endif namespace cocoon { StatusItem::StatusItem() : StatusItem(Adopt{cocoon::internal::retain([[::NSStatusItem alloc] init])}) { -#ifdef COCOON_MACOS_27 - StatusItem::install_expanded_interface_delegate_delegate_(handle()); -#endif } StatusItem::StatusItem(std::nullptr_t) : Object(nullptr) @@ -77,16 +15,6 @@ - (BOOL)respondsToSelector:(SEL)selector { } - std::string StatusItem::action() const - { - return cocoon::internal::from(NSStringFromSelector([cocoon::internal::ns<::NSStatusItem>(this) action])); - } - - void StatusItem::set_action(const std::string& value) const - { - [cocoon::internal::ns<::NSStatusItem>(this) setAction:NSSelectorFromString(cocoon::internal::to(value))]; - } - std::string StatusItem::autosave_name() const { return cocoon::internal::from([cocoon::internal::ns<::NSStatusItem>(this) autosaveName]); @@ -112,18 +40,6 @@ - (BOOL)respondsToSelector:(SEL)selector return cocoon::internal::wrap([cocoon::internal::ns<::NSStatusItem>(this) button]); } -#ifdef COCOON_MACOS_27 - StatusItemExpandedInterfaceSession StatusItem::expanded_interface_session() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSStatusItem>(this) expandedInterfaceSession]); - } - return StatusItemExpandedInterfaceSession(nullptr); - } - -#endif - double StatusItem::length() const { return static_cast([cocoon::internal::ns<::NSStatusItem>(this) length]); @@ -149,26 +65,6 @@ - (BOOL)respondsToSelector:(SEL)selector return cocoon::internal::wrap([cocoon::internal::ns<::NSStatusItem>(this) statusBar]); } - Object StatusItem::target() const - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSStatusItem>(this) target]); - } - - void StatusItem::set_target(const Object& value) const - { - [cocoon::internal::ns<::NSStatusItem>(this) setTarget:cocoon::internal::native_id(value)]; - } - - View StatusItem::view() const - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSStatusItem>(this) view]); - } - - void StatusItem::set_view(const View& value) const - { - [cocoon::internal::ns<::NSStatusItem>(this) setView:cocoon::internal::native<::NSView>(value)]; - } - bool StatusItem::is_visible() const { return static_cast([cocoon::internal::ns<::NSStatusItem>(this) isVisible]); @@ -178,21 +74,4 @@ - (BOOL)respondsToSelector:(SEL)selector { [cocoon::internal::ns<::NSStatusItem>(this) setVisible:static_cast<::BOOL>(value)]; } - -#ifdef COCOON_MACOS_27 - void StatusItem::install_expanded_interface_delegate_delegate_(void* native) - { - ::NSStatusItem* host = (__bridge ::NSStatusItem*)native; - AKStatusItemExpandedInterfaceDelegateDelegate* delegate = [[AKStatusItemExpandedInterfaceDelegateDelegate alloc] init]; - delegate->host = host; - host.expandedInterfaceDelegate = delegate; - __weak::NSStatusItem* weakHost = host; - cocoon::internal::keep_delegate(host, delegate, ^{ - ::NSStatusItem* strongHost = weakHost; - strongHost.expandedInterfaceDelegate = nil; - strongHost.expandedInterfaceDelegate = delegate; - }); - } - -#endif } diff --git a/src/generated/status_item_expanded_interface_session.mm b/src/generated/status_item_expanded_interface_session.mm deleted file mode 100644 index 75babfd5..00000000 --- a/src/generated/status_item_expanded_interface_session.mm +++ /dev/null @@ -1,31 +0,0 @@ -#include "generated/status_item_expanded_interface_session.h" -#include "internal.h" - -#ifdef COCOON_MACOS_27 -namespace cocoon -{ - StatusItemExpandedInterfaceSession::StatusItemExpandedInterfaceSession() : StatusItemExpandedInterfaceSession(Adopt{cocoon::internal::retain([[::NSStatusItemExpandedInterfaceSession alloc] init])}) - { - } - - StatusItemExpandedInterfaceSession::StatusItemExpandedInterfaceSession(std::nullptr_t) : Object(nullptr) - { - } - - StatusItemExpandedInterfaceSession::StatusItemExpandedInterfaceSession(Adopt adopt) : Object(adopt) - { - } - -#ifdef COCOON_MACOS_27 - void StatusItemExpandedInterfaceSession::cancel() const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSStatusItemExpandedInterfaceSession>(this) cancel]; - } - } - -#endif -} - -#endif diff --git a/src/generated/text_block.mm b/src/generated/text_block.mm index e4ed5ae3..ac684e02 100644 --- a/src/generated/text_block.mm +++ b/src/generated/text_block.mm @@ -20,18 +20,6 @@ return cocoon::internal::wrap([cocoon::internal::ns<::NSTextBlock>(this) borderColorForEdge:static_cast<::NSRectEdge>(edge)]); } -#ifdef COCOON_MACOS_27 - Color TextBlock::border_color_for_rect_edge(CGRectEdge rect_edge) const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSTextBlock>(this) borderColorForRectEdge:static_cast<::CGRectEdge>(rect_edge)]); - } - return Color(nullptr); - } - -#endif - Rect TextBlock::bounds_rect_for_content_rect(const Rect& content_rect, const Rect& rect, const TextContainer& text_container, const Range& char_range) const { return cocoon::internal::from([cocoon::internal::ns<::NSTextBlock>(this) boundsRectForContentRect:cocoon::internal::to(content_rect) inRect:cocoon::internal::to(rect) textContainer:cocoon::internal::native<::NSTextContainer>(text_container) characterRange:cocoon::internal::to(char_range)]); @@ -57,30 +45,19 @@ [cocoon::internal::ns<::NSTextBlock>(this) setBorderColor:cocoon::internal::native<::NSColor>(color) forEdge:static_cast<::NSRectEdge>(edge)]; } -#ifdef COCOON_MACOS_27 - void TextBlock::set_border_color(const Color& border_color, CGRectEdge rect_edge) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextBlock>(this) setBorderColor:cocoon::internal::native<::NSColor>(border_color) rectEdge:static_cast<::CGRectEdge>(rect_edge)]; - } - } - -#endif - - void TextBlock::set_content_width(double content_width, TextBlockValueType type) const + void TextBlock::set_content_width(double val, TextBlockValueType type) const { - [cocoon::internal::ns<::NSTextBlock>(this) setContentWidth:static_cast<::CGFloat>(content_width) type:static_cast<::NSTextBlockValueType>(type)]; + [cocoon::internal::ns<::NSTextBlock>(this) setContentWidth:static_cast<::CGFloat>(val) type:static_cast<::NSTextBlockValueType>(type)]; } - void TextBlock::set_value(double value, TextBlockValueType type, TextBlockDimension dimension) const + void TextBlock::set_value(double val, TextBlockValueType type, TextBlockDimension dimension) const { - [cocoon::internal::ns<::NSTextBlock>(this) setValue:static_cast<::CGFloat>(value) type:static_cast<::NSTextBlockValueType>(type) forDimension:static_cast<::NSTextBlockDimension>(dimension)]; + [cocoon::internal::ns<::NSTextBlock>(this) setValue:static_cast<::CGFloat>(val) type:static_cast<::NSTextBlockValueType>(type) forDimension:static_cast<::NSTextBlockDimension>(dimension)]; } - void TextBlock::set_width(double width, TextBlockValueType type, TextBlockLayer layer) const + void TextBlock::set_width(double val, TextBlockValueType type, TextBlockLayer layer) const { - [cocoon::internal::ns<::NSTextBlock>(this) setWidth:static_cast<::CGFloat>(width) type:static_cast<::NSTextBlockValueType>(type) forLayer:static_cast<::NSTextBlockLayer>(layer)]; + [cocoon::internal::ns<::NSTextBlock>(this) setWidth:static_cast<::CGFloat>(val) type:static_cast<::NSTextBlockValueType>(type) forLayer:static_cast<::NSTextBlockLayer>(layer)]; } void TextBlock::set_width(double val, TextBlockValueType type, TextBlockLayer layer, RectEdge edge) const @@ -88,17 +65,6 @@ [cocoon::internal::ns<::NSTextBlock>(this) setWidth:static_cast<::CGFloat>(val) type:static_cast<::NSTextBlockValueType>(type) forLayer:static_cast<::NSTextBlockLayer>(layer) edge:static_cast<::NSRectEdge>(edge)]; } -#ifdef COCOON_MACOS_27 - void TextBlock::set_width(double width, TextBlockValueType type, TextBlockLayer layer, CGRectEdge rect_edge) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextBlock>(this) setWidth:static_cast<::CGFloat>(width) type:static_cast<::NSTextBlockValueType>(type) forLayer:static_cast<::NSTextBlockLayer>(layer) rectEdge:static_cast<::CGRectEdge>(rect_edge)]; - } - } - -#endif - double TextBlock::value_for_dimension(TextBlockDimension dimension) const { return static_cast([cocoon::internal::ns<::NSTextBlock>(this) valueForDimension:static_cast<::NSTextBlockDimension>(dimension)]); @@ -114,35 +80,11 @@ return static_cast([cocoon::internal::ns<::NSTextBlock>(this) widthForLayer:static_cast<::NSTextBlockLayer>(layer) edge:static_cast<::NSRectEdge>(edge)]); } -#ifdef COCOON_MACOS_27 - double TextBlock::width_for_layer(TextBlockLayer layer, CGRectEdge rect_edge) const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSTextBlock>(this) widthForLayer:static_cast<::NSTextBlockLayer>(layer) rectEdge:static_cast<::CGRectEdge>(rect_edge)]); - } - return {}; - } - -#endif - TextBlockValueType TextBlock::width_value_type_for_layer(TextBlockLayer layer, RectEdge edge) const { return static_cast([cocoon::internal::ns<::NSTextBlock>(this) widthValueTypeForLayer:static_cast<::NSTextBlockLayer>(layer) edge:static_cast<::NSRectEdge>(edge)]); } -#ifdef COCOON_MACOS_27 - TextBlockValueType TextBlock::width_value_type_for_layer(TextBlockLayer layer, CGRectEdge rect_edge) const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSTextBlock>(this) widthValueTypeForLayer:static_cast<::NSTextBlockLayer>(layer) rectEdge:static_cast<::CGRectEdge>(rect_edge)]); - } - return {}; - } - -#endif - Color TextBlock::background_color() const { return cocoon::internal::wrap([cocoon::internal::ns<::NSTextBlock>(this) backgroundColor]); diff --git a/src/generated/text_container.mm b/src/generated/text_container.mm index ff65eb52..54ffa70b 100644 --- a/src/generated/text_container.mm +++ b/src/generated/text_container.mm @@ -29,11 +29,6 @@ return cocoon::internal::from([cocoon::internal::ns<::NSTextContainer>(this) lineFragmentRectForProposedRect:cocoon::internal::to(proposed_rect) sweepDirection:static_cast<::NSLineSweepDirection>(sweep_direction) movementDirection:static_cast<::NSLineMovementDirection>(movement_direction) remainingRect:(::NSRectPointer)(remaining_rect)]); } - void TextContainer::replace_layout_manager(const LayoutManager& new_layout_manager) const - { - [cocoon::internal::ns<::NSTextContainer>(this) replaceLayoutManager:cocoon::internal::native<::NSLayoutManager>(new_layout_manager)]; - } - Size TextContainer::container_size() const { return cocoon::internal::from([cocoon::internal::ns<::NSTextContainer>(this) containerSize]); @@ -44,22 +39,6 @@ [cocoon::internal::ns<::NSTextContainer>(this) setContainerSize:cocoon::internal::to(value)]; } - std::vector TextContainer::exclusion_paths() const - { - return cocoon::internal::from_array([cocoon::internal::ns<::NSTextContainer>(this) exclusionPaths], [](id e) -> BezierPath - { - return cocoon::internal::wrap((::NSBezierPath*)e); - }); - } - - void TextContainer::set_exclusion_paths(const std::vector& value) const - { - [cocoon::internal::ns<::NSTextContainer>(this) setExclusionPaths:cocoon::internal::to_array(value, [](const BezierPath& e) -> id - { - return cocoon::internal::native<::NSBezierPath>(e); - })]; - } - bool TextContainer::height_tracks_text_view() const { return static_cast([cocoon::internal::ns<::NSTextContainer>(this) heightTracksTextView]); @@ -70,16 +49,6 @@ [cocoon::internal::ns<::NSTextContainer>(this) setHeightTracksTextView:static_cast<::BOOL>(value)]; } - LayoutManager TextContainer::layout_manager() const - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSTextContainer>(this) layoutManager]); - } - - void TextContainer::set_layout_manager(const LayoutManager& value) const - { - [cocoon::internal::ns<::NSTextContainer>(this) setLayoutManager:cocoon::internal::native<::NSLayoutManager>(value)]; - } - LineBreakMode TextContainer::line_break_mode() const { return static_cast([cocoon::internal::ns<::NSTextContainer>(this) lineBreakMode]); @@ -130,16 +99,6 @@ return cocoon::internal::wrap([cocoon::internal::ns<::NSTextContainer>(this) textLayoutManager]); } - TextView TextContainer::text_view() const - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSTextContainer>(this) textView]); - } - - void TextContainer::set_text_view(const TextView& value) const - { - [cocoon::internal::ns<::NSTextContainer>(this) setTextView:cocoon::internal::native<::NSTextView>(value)]; - } - bool TextContainer::width_tracks_text_view() const { return static_cast([cocoon::internal::ns<::NSTextContainer>(this) widthTracksTextView]); diff --git a/src/generated/text_field.mm b/src/generated/text_field.mm index 0d07ac5f..8719e6a0 100644 --- a/src/generated/text_field.mm +++ b/src/generated/text_field.mm @@ -383,29 +383,6 @@ - (BOOL)respondsToSelector:(SEL)selector [cocoon::internal::ns<::NSTextField>(this) setBezeled:static_cast<::BOOL>(value)]; } -#ifdef COCOON_MACOS_27 - ControlBorderShape TextField::border_shape() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSTextField>(this) borderShape]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void TextField::set_border_shape(ControlBorderShape value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextField>(this) setBorderShape:static_cast<::NSControlBorderShape>(value)]; - } - } - -#endif - bool TextField::is_bordered() const { return static_cast([cocoon::internal::ns<::NSTextField>(this) isBordered]); diff --git a/src/generated/text_layout_manager.mm b/src/generated/text_layout_manager.mm index e69dd195..0ecb3129 100644 --- a/src/generated/text_layout_manager.mm +++ b/src/generated/text_layout_manager.mm @@ -57,33 +57,6 @@ - (BOOL)textLayoutManager:(NSTextLayoutManager*)textLayoutManager shouldBreakLin }); } -#ifdef COCOON_MACOS_27 -- (void)textLayoutManager:(NSTextLayoutManager*)textLayoutManager cacheTextAttachmentViewProvider:(NSTextAttachmentViewProvider*)viewProvider forTextAttachment:(NSTextAttachment*)textAttachment -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "cache_text_attachment_view_provider_for_text_attachment", cocoon::internal::wrap(viewProvider), cocoon::internal::wrap(textAttachment)); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (NSTextAttachmentViewProvider*)textLayoutManager:(NSTextLayoutManager*)textLayoutManager retrieveCachedTextAttachmentViewProviderForTextAttachment:(NSTextAttachment*)attachment -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "retrieve_cached_text_attachment_view_provider_for_text_attachment", cocoon::internal::wrap(attachment)); - return cocoon::internal::native<::NSTextAttachmentViewProvider>(__r); -} - -#endif - - (BOOL)respondsToSelector:(SEL)selector { id strongHost = host; @@ -99,20 +72,6 @@ - (BOOL)respondsToSelector:(SEL)selector { return strongHost && cocoon::Signal(cocoon::Object, cocoon::Object, std::map)>::connected((__bridge void*)strongHost, "rendering_attributes_for_link_at_location_default_attributes"); } -#ifdef COCOON_MACOS_27 - if (selector == @selector(textLayoutManager:cacheTextAttachmentViewProvider:forTextAttachment:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "cache_text_attachment_view_provider_for_text_attachment"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(textLayoutManager:retrieveCachedTextAttachmentViewProviderForTextAttachment:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "retrieve_cached_text_attachment_view_provider_for_text_attachment"); - } -#endif - return [super respondsToSelector:selector]; } diff --git a/src/generated/text_selection_manager.mm b/src/generated/text_selection_manager.mm deleted file mode 100644 index 5a1f4003..00000000 --- a/src/generated/text_selection_manager.mm +++ /dev/null @@ -1,438 +0,0 @@ -#include "generated/text_selection_manager.h" -#include "internal.h" - -#ifdef COCOON_MACOS_27 -@interface AKTextSelectionManagerDelegate : NSObject -{ -@public - __weak id host; -} -@end - -@implementation AKTextSelectionManagerDelegate - -#ifdef COCOON_MACOS_27 -- (BOOL)selectionManager:(NSTextSelectionManager*)selectionManager shouldBeginSelectionAtPoint:(NSPoint)point -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "selection_manager_should_begin_selection_at_point", cocoon::internal::from(point)); - return static_cast<::BOOL>(__r); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (void)selectionManagerWillBeginSelection:(NSTextSelectionManager*)selectionManager -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "selection_manager_will_begin_selection"); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (void)selectionManagerDidEndSelection:(NSTextSelectionManager*)selectionManager -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "selection_manager_did_end_selection"); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (id)selectionManager:(NSTextSelectionManager*)selectionManager locationOfTextContainerAtPoint:(NSPoint)point -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "selection_manager_location_of_text_container_at_point", cocoon::internal::from(point)); - return cocoon::internal::native_id(__r); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (NSRect)selectionManager:(NSTextSelectionManager*)selectionManager frameOfTextContainerAtPoint:(NSPoint)point -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "selection_manager_frame_of_text_container_at_point", cocoon::internal::from(point)); - return cocoon::internal::to(__r); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (NSDraggingSession*)selectionManager:(NSTextSelectionManager*)selectionManager makeDraggingSessionWithGesture:(NSGestureRecognizer*)gesture -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "selection_manager_make_dragging_session_with_gesture", cocoon::internal::wrap(gesture)); - return cocoon::internal::native<::NSDraggingSession>(__r); -} - -#endif - -- (BOOL)respondsToSelector:(SEL)selector -{ - id strongHost = host; -#ifdef COCOON_MACOS_27 - if (selector == @selector(selectionManager:shouldBeginSelectionAtPoint:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "selection_manager_should_begin_selection_at_point"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(selectionManagerWillBeginSelection:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "selection_manager_will_begin_selection"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(selectionManagerDidEndSelection:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "selection_manager_did_end_selection"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(selectionManager:locationOfTextContainerAtPoint:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "selection_manager_location_of_text_container_at_point"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(selectionManager:frameOfTextContainerAtPoint:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "selection_manager_frame_of_text_container_at_point"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(selectionManager:makeDraggingSessionWithGesture:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "selection_manager_make_dragging_session_with_gesture"); - } -#endif - - return [super respondsToSelector:selector]; -} - -@end - -@interface AKTextSelectionManagerTextSelectionDataSourceDelegate : NSObject -{ -@public - __weak id host; -} -@end - -@implementation AKTextSelectionManagerTextSelectionDataSourceDelegate - -- (void)enumerateSubstringsFromLocation:(id)location options:(NSStringEnumerationOptions)options usingBlock:(void(NS_NOESCAPE ^)(NSString*, NSTextRange*, NSTextRange*, BOOL*))block -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal)>::emit((__bridge void*)strongHost, "enumerate_substrings_from_location_options_using_block", static_cast(options), [&]() -> std::function - { - auto blk = (void (^)(::NSString*, ::NSTextRange*, ::NSTextRange*, BOOL*))(block); - if (!blk) - { - return {}; - } - return [blk](std::string a283_0, cocoon::TextRange a283_1, cocoon::TextRange a283_2, bool& a283_3) -> void - { - ::BOOL __o283_3 = static_cast<::BOOL>(a283_3); - blk(cocoon::internal::to(a283_0), cocoon::internal::native<::NSTextRange>(a283_1), cocoon::internal::native<::NSTextRange>(a283_2), &__o283_3); - a283_3 = static_cast(__o283_3); - }; - }()); -} - -- (NSTextRange*)textRangeForSelectionGranularity:(NSTextSelectionGranularity)selectionGranularity enclosingLocation:(id)location -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "text_range_for_selection_granularity_enclosing_location", cocoon::internal::wrap(location)); - return cocoon::internal::native<::NSTextRange>(__r); -} - -- (id)locationFromLocation:(id)location withOffset:(NSInteger)offset -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "location_from_location_with_offset", static_cast(offset)); - return cocoon::internal::native_id(__r); -} - -- (NSInteger)offsetFromLocation:(id)from toLocation:(id)to -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "offset_from_location_to_location", cocoon::internal::wrap(to)); - return static_cast<::NSInteger>(__r); -} - -- (NSTextSelectionNavigationWritingDirection)baseWritingDirectionAtLocation:(id)location -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "base_writing_direction_at_location"); - return static_cast<::NSTextSelectionNavigationWritingDirection>(__r); -} - -- (void)enumerateCaretOffsetsInLineFragmentAtLocation:(id)location usingBlock:(void(NS_NOESCAPE ^)(CGFloat, id, BOOL, BOOL*))block -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal)>::emit((__bridge void*)strongHost, "enumerate_caret_offsets_in_line_fragment_at_location_using_block", [&]() -> std::function - { - auto blk = (void (^)(::CGFloat, id, BOOL, BOOL*))(block); - if (!blk) - { - return {}; - } - return [blk](double a284_0, cocoon::Object a284_1, bool a284_2, bool& a284_3) -> void - { - ::BOOL __o284_3 = static_cast<::BOOL>(a284_3); - blk(static_cast<::CGFloat>(a284_0), cocoon::internal::native_id(a284_1), static_cast<::BOOL>(a284_2), &__o284_3); - a284_3 = static_cast(__o284_3); - }; - }()); -} - -- (NSTextRange*)lineFragmentRangeForPoint:(CGPoint)point inContainerAtLocation:(id)location -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "line_fragment_range_for_point_in_container_at_location", cocoon::internal::wrap(location)); - return cocoon::internal::native<::NSTextRange>(__r); -} - -- (void)enumerateContainerBoundariesFromLocation:(id)location reverse:(BOOL)reverse usingBlock:(void(NS_NOESCAPE ^)(id, BOOL*))block -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal)>::emit((__bridge void*)strongHost, "enumerate_container_boundaries_from_location_reverse_using_block", static_cast(reverse), [&]() -> std::function - { - auto blk = (void (^)(id, BOOL*))(block); - if (!blk) - { - return {}; - } - return [blk](cocoon::Object a285_0, bool& a285_1) -> void - { - ::BOOL __o285_1 = static_cast<::BOOL>(a285_1); - blk(cocoon::internal::native_id(a285_0), &__o285_1); - a285_1 = static_cast(__o285_1); - }; - }()); -} - -- (NSTextSelectionNavigationLayoutOrientation)textLayoutOrientationAtLocation:(id)location -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "text_layout_orientation_at_location"); - return static_cast<::NSTextSelectionNavigationLayoutOrientation>(__r); -} - -#ifdef COCOON_MACOS_27 -- (CGPoint)convertInteractionPoint:(CGPoint)point toContainerAtLocation:(id)containerLocation -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "convert_interaction_point_to_container_at_location", cocoon::internal::wrap(containerLocation)); - return cocoon::internal::to(__r); -} - -#endif - -- (BOOL)respondsToSelector:(SEL)selector -{ - id strongHost = host; - if (selector == @selector(enumerateSubstringsFromLocation:options:usingBlock:)) - { - return strongHost && cocoon::Signal)>::connected((__bridge void*)strongHost, "enumerate_substrings_from_location_options_using_block"); - } - if (selector == @selector(textRangeForSelectionGranularity:enclosingLocation:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "text_range_for_selection_granularity_enclosing_location"); - } - if (selector == @selector(locationFromLocation:withOffset:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "location_from_location_with_offset"); - } - if (selector == @selector(offsetFromLocation:toLocation:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "offset_from_location_to_location"); - } - if (selector == @selector(baseWritingDirectionAtLocation:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "base_writing_direction_at_location"); - } - if (selector == @selector(enumerateCaretOffsetsInLineFragmentAtLocation:usingBlock:)) - { - return strongHost && cocoon::Signal)>::connected((__bridge void*)strongHost, "enumerate_caret_offsets_in_line_fragment_at_location_using_block"); - } - if (selector == @selector(lineFragmentRangeForPoint:inContainerAtLocation:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "line_fragment_range_for_point_in_container_at_location"); - } - if (selector == @selector(enumerateContainerBoundariesFromLocation:reverse:usingBlock:)) - { - return strongHost && cocoon::Signal)>::connected((__bridge void*)strongHost, "enumerate_container_boundaries_from_location_reverse_using_block"); - } - if (selector == @selector(textLayoutOrientationAtLocation:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "text_layout_orientation_at_location"); - } -#ifdef COCOON_MACOS_27 - if (selector == @selector(convertInteractionPoint:toContainerAtLocation:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "convert_interaction_point_to_container_at_location"); - } -#endif - - return [super respondsToSelector:selector]; -} - -@end - -namespace cocoon -{ - TextSelectionManager::TextSelectionManager() : TextSelectionManager(Adopt{cocoon::internal::retain([[::NSTextSelectionManager alloc] init])}) - { - TextSelectionManager::install_delegate_delegate_(handle()); - TextSelectionManager::install_text_selection_data_source_delegate_(handle()); - } - - TextSelectionManager::TextSelectionManager(std::nullptr_t) : Object(nullptr) - { - } - - TextSelectionManager::TextSelectionManager(Adopt adopt) : Object(adopt) - { - } - -#ifdef COCOON_MACOS_27 - std::vector TextSelectionManager::gestures_for_failure_requirements() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::from_array([cocoon::internal::ns<::NSTextSelectionManager>(this) gesturesForFailureRequirements], [](id e) -> GestureRecognizer - { - return cocoon::internal::wrap((::NSGestureRecognizer*)e); - }); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - TextSelectionMode TextSelectionManager::text_selection_mode() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSTextSelectionManager>(this) textSelectionMode]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void TextSelectionManager::set_text_selection_mode(TextSelectionMode value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextSelectionManager>(this) setTextSelectionMode:static_cast<::NSTextSelectionMode>(value)]; - } - } - -#endif - - void TextSelectionManager::install_delegate_delegate_(void* native) - { - ::NSTextSelectionManager* host = (__bridge ::NSTextSelectionManager*)native; - AKTextSelectionManagerDelegate* delegate = [[AKTextSelectionManagerDelegate alloc] init]; - delegate->host = host; - host.delegate = delegate; - __weak::NSTextSelectionManager* weakHost = host; - cocoon::internal::keep_delegate(host, delegate, ^{ - ::NSTextSelectionManager* strongHost = weakHost; - strongHost.delegate = nil; - strongHost.delegate = delegate; - }); - } - - void TextSelectionManager::install_text_selection_data_source_delegate_(void* native) - { - ::NSTextSelectionManager* host = (__bridge ::NSTextSelectionManager*)native; - AKTextSelectionManagerTextSelectionDataSourceDelegate* delegate = [[AKTextSelectionManagerTextSelectionDataSourceDelegate alloc] init]; - delegate->host = host; - host.textSelectionDataSource = delegate; - __weak::NSTextSelectionManager* weakHost = host; - cocoon::internal::keep_delegate(host, delegate, ^{ - ::NSTextSelectionManager* strongHost = weakHost; - strongHost.textSelectionDataSource = nil; - strongHost.textSelectionDataSource = delegate; - }); - } -} - -#endif diff --git a/src/generated/text_tab.mm b/src/generated/text_tab.mm index 6ef4cf85..96670eac 100644 --- a/src/generated/text_tab.mm +++ b/src/generated/text_tab.mm @@ -3,19 +3,6 @@ namespace cocoon { - TextTab::TextTab(TextAlignment alignment, double loc, const std::map& options) : TextTab(Adopt{cocoon::internal::retain([[::NSTextTab alloc] initWithTextAlignment:static_cast<::NSTextAlignment>(alignment) - location:static_cast<::CGFloat>(loc) - options:cocoon::internal::to_dictionary(options, [](const std::string& k) -> id - { - return cocoon::internal::to(k); - }, - [](const Object& v) -> id - { - return cocoon::internal::native_id(v); - })])}) - { - } - TextTab::TextTab(TextTabType type, double loc) : TextTab(Adopt{cocoon::internal::retain([[::NSTextTab alloc] initWithType:static_cast<::NSTextTabType>(type) location:static_cast<::CGFloat>(loc)])}) { } @@ -37,11 +24,6 @@ return cocoon::internal::wrap([::NSTextTab columnTerminatorsForLocale:cocoon::internal::native<::NSLocale>(a_locale)]); } - TextAlignment TextTab::alignment() const - { - return static_cast([cocoon::internal::ns<::NSTextTab>(this) alignment]); - } - double TextTab::location() const { return static_cast([cocoon::internal::ns<::NSTextTab>(this) location]); diff --git a/src/generated/text_table.mm b/src/generated/text_table.mm index 291527b8..871eb358 100644 --- a/src/generated/text_table.mm +++ b/src/generated/text_table.mm @@ -60,13 +60,13 @@ [cocoon::internal::ns<::NSTextTable>(this) setLayoutAlgorithm:static_cast<::NSTextTableLayoutAlgorithm>(value)]; } - std::int64_t TextTable::number_of_columns() const + std::uint64_t TextTable::number_of_columns() const { - return static_cast([cocoon::internal::ns<::NSTextTable>(this) numberOfColumns]); + return static_cast([cocoon::internal::ns<::NSTextTable>(this) numberOfColumns]); } - void TextTable::set_number_of_columns(std::int64_t value) const + void TextTable::set_number_of_columns(std::uint64_t value) const { - [cocoon::internal::ns<::NSTextTable>(this) setNumberOfColumns:static_cast<::NSInteger>(value)]; + [cocoon::internal::ns<::NSTextTable>(this) setNumberOfColumns:static_cast<::NSUInteger>(value)]; } } diff --git a/src/generated/text_table_block.mm b/src/generated/text_table_block.mm index f3a4005b..44e4e0ad 100644 --- a/src/generated/text_table_block.mm +++ b/src/generated/text_table_block.mm @@ -3,7 +3,7 @@ namespace cocoon { - TextTableBlock::TextTableBlock(const TextTable& table, std::int64_t row, std::int64_t row_span, std::int64_t column, std::int64_t column_span) : TextTableBlock(Adopt{cocoon::internal::retain([[::NSTextTableBlock alloc] initWithTable:cocoon::internal::native<::NSTextTable>(table) startingRow:static_cast<::NSInteger>(row) rowSpan:static_cast<::NSInteger>(row_span) startingColumn:static_cast<::NSInteger>(column) columnSpan:static_cast<::NSInteger>(column_span)])}) + TextTableBlock::TextTableBlock(const TextTable& table, std::int64_t row, std::int64_t row_span, std::int64_t col, std::int64_t col_span) : TextTableBlock(Adopt{cocoon::internal::retain([[::NSTextTableBlock alloc] initWithTable:cocoon::internal::native<::NSTextTable>(table) startingRow:static_cast<::NSInteger>(row) rowSpan:static_cast<::NSInteger>(row_span) startingColumn:static_cast<::NSInteger>(col) columnSpan:static_cast<::NSInteger>(col_span)])}) { } diff --git a/src/generated/text_view.mm b/src/generated/text_view.mm index 913d818a..f4041381 100644 --- a/src/generated/text_view.mm +++ b/src/generated/text_view.mm @@ -930,17 +930,6 @@ - (BOOL)respondsToSelector:(SEL)selector [::NSTextView registerForServices]; } -#ifdef COCOON_MACOS_27 - void TextView::register_text_attachment_view_provider_reuse_policy(TextAttachmentViewProviderReusePolicy policy, const std::string& view_provider_type) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextView>(this) registerTextAttachmentViewProviderReusePolicy:static_cast<::NSTextAttachmentViewProviderReusePolicy>(policy) forTextAttachmentViewProviderType:NSClassFromString(cocoon::internal::to(view_provider_type))]; - } - } - -#endif - void TextView::replace_text_container(const TextContainer& new_container) const { [cocoon::internal::ns<::NSTextView>(this) replaceTextContainer:cocoon::internal::native<::NSTextContainer>(new_container)]; @@ -1092,50 +1081,6 @@ - (BOOL)respondsToSelector:(SEL)selector return cocoon::internal::wrap([::NSTextView textViewUsingTextLayoutManager:static_cast<::BOOL>(using_text_layout_manager)]); } -#ifdef COCOON_MACOS_27 - void TextView::text_viewport_layout_controller(const TextViewportLayoutController& text_viewport_layout_controller, const TextLayoutFragment& text_layout_fragment) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextView>(this) textViewportLayoutController:cocoon::internal::native<::NSTextViewportLayoutController>(text_viewport_layout_controller) configureRenderingSurfaceForTextLayoutFragment:cocoon::internal::native<::NSTextLayoutFragment>(text_layout_fragment)]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - void TextView::text_viewport_layout_controller_did_layout(const TextViewportLayoutController& text_viewport_layout_controller) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextView>(this) textViewportLayoutControllerDidLayout:cocoon::internal::native<::NSTextViewportLayoutController>(text_viewport_layout_controller)]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - void TextView::text_viewport_layout_controller_received_set_needs_layout(const TextViewportLayoutController& text_viewport_layout_controller) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextView>(this) textViewportLayoutControllerReceivedSetNeedsLayout:cocoon::internal::native<::NSTextViewportLayoutController>(text_viewport_layout_controller)]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - void TextView::text_viewport_layout_controller_will_layout(const TextViewportLayoutController& text_viewport_layout_controller) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSTextView>(this) textViewportLayoutControllerWillLayout:cocoon::internal::native<::NSTextViewportLayoutController>(text_viewport_layout_controller)]; - } - } - -#endif - void TextView::tighten_kerning(const Object& sender) const { [cocoon::internal::ns<::NSTextView>(this) tightenKerning:cocoon::internal::native_id(sender)]; @@ -1266,18 +1211,6 @@ - (BOOL)respondsToSelector:(SEL)selector return cocoon::internal::wrap([cocoon::internal::ns<::NSTextView>(this) validRequestorForSendType:cocoon::internal::to(send_type) returnType:cocoon::internal::to(return_type)]); } -#ifdef COCOON_MACOS_27 - Rect TextView::viewport_bounds_for_text_viewport_layout_controller(const TextViewportLayoutController& text_viewport_layout_controller) const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::from([cocoon::internal::ns<::NSTextView>(this) viewportBoundsForTextViewportLayoutController:cocoon::internal::native<::NSTextViewportLayoutController>(text_viewport_layout_controller)]); - } - return {}; - } - -#endif - bool TextView::write_selection_to_pasteboard(const Pasteboard& pboard, const std::string& type) const { return static_cast([cocoon::internal::ns<::NSTextView>(this) writeSelectionToPasteboard:cocoon::internal::native<::NSPasteboard>(pboard) type:cocoon::internal::to(type)]); diff --git a/src/generated/text_viewport_layout_controller.mm b/src/generated/text_viewport_layout_controller.mm index b8679b8d..43aeb079 100644 --- a/src/generated/text_viewport_layout_controller.mm +++ b/src/generated/text_viewport_layout_controller.mm @@ -51,43 +51,6 @@ - (void)textViewportLayoutControllerDidLayout:(NSTextViewportLayoutController*)t cocoon::Signal::emit((__bridge void*)strongHost, "did_layout"); } -#ifdef COCOON_MACOS_27 -- (void)textViewportLayoutController:(NSTextViewportLayoutController*)textViewportLayoutController cacheRenderingSurface:(id)renderingSurface forKey:(id)renderingSurfaceKey -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "cache_rendering_surface_for_key", cocoon::internal::wrap(renderingSurface), cocoon::internal::wrap(renderingSurfaceKey)); -} - -#endif - -#ifdef COCOON_MACOS_27 -- (id)textViewportLayoutController:(NSTextViewportLayoutController*)textViewportLayoutController retrieveCachedRenderingSurfaceForKey:(id)renderingSurfaceKey -{ - id strongHost = host; - if (!strongHost) - { - return {}; - } - auto __r = cocoon::Signal::emit((__bridge void*)strongHost, "retrieve_cached_rendering_surface_for_key", cocoon::internal::wrap(renderingSurfaceKey)); - return cocoon::internal::native_id(__r); -} - -#endif - -- (void)textViewportLayoutControllerReceivedSetNeedsLayout:(NSTextViewportLayoutController*)textViewportLayoutController -{ - id strongHost = host; - if (!strongHost) - { - return; - } - cocoon::Signal::emit((__bridge void*)strongHost, "received_set_needs_layout"); -} - - (BOOL)respondsToSelector:(SEL)selector { id strongHost = host; @@ -107,24 +70,6 @@ - (BOOL)respondsToSelector:(SEL)selector { return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "did_layout"); } -#ifdef COCOON_MACOS_27 - if (selector == @selector(textViewportLayoutController:cacheRenderingSurface:forKey:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "cache_rendering_surface_for_key"); - } -#endif - -#ifdef COCOON_MACOS_27 - if (selector == @selector(textViewportLayoutController:retrieveCachedRenderingSurfaceForKey:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "retrieve_cached_rendering_surface_for_key"); - } -#endif - - if (selector == @selector(textViewportLayoutControllerReceivedSetNeedsLayout:)) - { - return strongHost && cocoon::Signal::connected((__bridge void*)strongHost, "received_set_needs_layout"); - } return [super respondsToSelector:selector]; } diff --git a/src/generated/toolbar_item_group.mm b/src/generated/toolbar_item_group.mm index 81d4a619..af1b59c6 100644 --- a/src/generated/toolbar_item_group.mm +++ b/src/generated/toolbar_item_group.mm @@ -68,29 +68,6 @@ [cocoon::internal::ns<::NSToolbarItemGroup>(this) setControlRepresentation:static_cast<::NSToolbarItemGroupControlRepresentation>(value)]; } -#ifdef COCOON_MACOS_27 - ToolbarItemGroupRole ToolbarItemGroup::role() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSToolbarItemGroup>(this) role]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void ToolbarItemGroup::set_role(ToolbarItemGroupRole value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSToolbarItemGroup>(this) setRole:static_cast<::NSToolbarItemGroupRole>(value)]; - } - } - -#endif - std::int64_t ToolbarItemGroup::selected_index() const { return static_cast([cocoon::internal::ns<::NSToolbarItemGroup>(this) selectedIndex]); diff --git a/src/generated/url_session_task.mm b/src/generated/url_session_task.mm index 1cbc39ce..0ef324bd 100644 --- a/src/generated/url_session_task.mm +++ b/src/generated/url_session_task.mm @@ -34,9 +34,9 @@ - (void)URLSession:(NSURLSession*)session didReceiveChallenge:(NSURLAuthenticati { return {}; } - return [blk](cocoon::URLSessionAuthChallengeDisposition a286_0, cocoon::URLCredential a286_1) -> void + return [blk](cocoon::URLSessionAuthChallengeDisposition a280_0, cocoon::URLCredential a280_1) -> void { - blk(static_cast<::NSURLSessionAuthChallengeDisposition>(a286_0), cocoon::internal::native<::NSURLCredential>(a286_1)); + blk(static_cast<::NSURLSessionAuthChallengeDisposition>(a280_0), cocoon::internal::native<::NSURLCredential>(a280_1)); }; }()); } @@ -75,9 +75,9 @@ - (void)URLSession:(NSURLSession*)session task:(NSURLSessionTask*)task willBegin { return {}; } - return [blk](cocoon::URLSessionDelayedRequestDisposition a287_0, cocoon::URLRequest a287_1) -> void + return [blk](cocoon::URLSessionDelayedRequestDisposition a281_0, cocoon::URLRequest a281_1) -> void { - blk(static_cast<::NSURLSessionDelayedRequestDisposition>(a287_0), cocoon::internal::native<::NSURLRequest>(a287_1)); + blk(static_cast<::NSURLSessionDelayedRequestDisposition>(a281_0), cocoon::internal::native<::NSURLRequest>(a281_1)); }; }()); } @@ -106,9 +106,9 @@ - (void)URLSession:(NSURLSession*)session task:(NSURLSessionTask*)task willPerfo { return {}; } - return [blk](cocoon::URLRequest a288_0) -> void + return [blk](cocoon::URLRequest a282_0) -> void { - blk(cocoon::internal::native<::NSURLRequest>(a288_0)); + blk(cocoon::internal::native<::NSURLRequest>(a282_0)); }; }()); } @@ -127,9 +127,9 @@ - (void)URLSession:(NSURLSession*)session task:(NSURLSessionTask*)task didReceiv { return {}; } - return [blk](cocoon::URLSessionAuthChallengeDisposition a289_0, cocoon::URLCredential a289_1) -> void + return [blk](cocoon::URLSessionAuthChallengeDisposition a283_0, cocoon::URLCredential a283_1) -> void { - blk(static_cast<::NSURLSessionAuthChallengeDisposition>(a289_0), cocoon::internal::native<::NSURLCredential>(a289_1)); + blk(static_cast<::NSURLSessionAuthChallengeDisposition>(a283_0), cocoon::internal::native<::NSURLCredential>(a283_1)); }; }()); } @@ -148,9 +148,9 @@ - (void)URLSession:(NSURLSession*)session task:(NSURLSessionTask*)task needNewBo { return {}; } - return [blk](cocoon::InputStream a290_0) -> void + return [blk](cocoon::InputStream a284_0) -> void { - blk(cocoon::internal::native<::NSInputStream>(a290_0)); + blk(cocoon::internal::native<::NSInputStream>(a284_0)); }; }()); } @@ -169,9 +169,9 @@ - (void)URLSession:(NSURLSession*)session task:(NSURLSessionTask*)task needNewBo { return {}; } - return [blk](cocoon::InputStream a291_0) -> void + return [blk](cocoon::InputStream a285_0) -> void { - blk(cocoon::internal::native<::NSInputStream>(a291_0)); + blk(cocoon::internal::native<::NSInputStream>(a285_0)); }; }()); } diff --git a/src/generated/view.mm b/src/generated/view.mm index ddd8f9a7..97b52d04 100644 --- a/src/generated/view.mm +++ b/src/generated/view.mm @@ -122,23 +122,6 @@ source:cocoon::internal::native_id(source)]); } -#ifdef COCOON_MACOS_27 - DraggingSession View::begin_dragging_session_with_items(const std::vector& items, const GestureRecognizer& gesture, const Object& source) const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) beginDraggingSessionWithItems:cocoon::internal::to_array(items, [](const DraggingItem& e) -> id - { - return cocoon::internal::native<::NSDraggingItem>(e); - }) - gesture:cocoon::internal::native<::NSGestureRecognizer>(gesture) - source:cocoon::internal::native_id(source)]); - } - return DraggingSession(nullptr); - } - -#endif - void View::begin_page_in_rect(const Rect& rect, const Point& location) const { [cocoon::internal::ns<::NSView>(this) beginPageInRect:cocoon::internal::to(rect) atPlacement:cocoon::internal::to(location)]; @@ -402,17 +385,6 @@ return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) hitTest:cocoon::internal::to(point)]); } -#ifdef COCOON_MACOS_27 - void View::invalidate_corner_configuration() const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSView>(this) invalidateCornerConfiguration]; - } - } - -#endif - void View::invalidate_intrinsic_content_size() const { [cocoon::internal::ns<::NSView>(this) invalidateIntrinsicContentSize]; @@ -769,17 +741,6 @@ [cocoon::internal::ns<::NSView>(this) viewDidChangeEffectiveAppearance]; } -#ifdef COCOON_MACOS_27 - void View::view_did_change_effective_corner_radii() const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSView>(this) viewDidChangeEffectiveCornerRadii]; - } - } - -#endif - void View::view_did_end_live_resize() const { [cocoon::internal::ns<::NSView>(this) viewDidEndLiveResize]; @@ -1045,18 +1006,6 @@ })]; } -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration View::corner_configuration() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) cornerConfiguration]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - FocusRingType View::default_focus_ring_type() { return static_cast([::NSView defaultFocusRingType]); @@ -1072,18 +1021,6 @@ return static_cast([cocoon::internal::ns<::NSView>(this) isDrawingFindIndicator]); } -#ifdef COCOON_MACOS_27 - ViewCornerRadii View::effective_corner_radii() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) effectiveCornerRadii]); - } - return ViewCornerRadii(nullptr); - } - -#endif - MenuItem View::enclosing_menu_item() const { return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) enclosingMenuItem]); @@ -1094,29 +1031,6 @@ return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) enclosingScrollView]); } -#ifdef COCOON_MACOS_27 - ViewExclusiveGestureBehavior View::exclusive_gesture_behavior() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSView>(this) exclusiveGestureBehavior]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - void View::set_exclusive_gesture_behavior(ViewExclusiveGestureBehavior value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSView>(this) setExclusiveGestureBehavior:static_cast<::NSViewExclusiveGestureBehavior>(value)]; - } - } - -#endif - LayoutYAxisAnchor View::first_baseline_anchor() const { return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) firstBaselineAnchor]); @@ -1565,29 +1479,6 @@ return static_cast([cocoon::internal::ns<::NSView>(this) tag]); } -#ifdef COCOON_MACOS_27 - TextSelectionManager View::text_selection_manager() const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSView>(this) textSelectionManager]); - } - return TextSelectionManager(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - void View::set_text_selection_manager(const TextSelectionManager& value) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSView>(this) setTextSelectionManager:cocoon::internal::native<::NSTextSelectionManager>(value)]; - } - } - -#endif - std::string View::tool_tip() const { return cocoon::internal::from([cocoon::internal::ns<::NSView>(this) toolTip]); diff --git a/src/generated/view_corner_configuration.mm b/src/generated/view_corner_configuration.mm deleted file mode 100644 index 50c920c3..00000000 --- a/src/generated/view_corner_configuration.mm +++ /dev/null @@ -1,164 +0,0 @@ -#include "generated/view_corner_configuration.h" -#include "internal.h" - -#ifdef COCOON_MACOS_27 -namespace cocoon -{ - ViewCornerConfiguration::ViewCornerConfiguration() : Object(nullptr) - { - } - - ViewCornerConfiguration::ViewCornerConfiguration(std::nullptr_t) : Object(nullptr) - { - } - - ViewCornerConfiguration::ViewCornerConfiguration(Adopt adopt) : Object(adopt) - { - } - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::capsule_corner_configuration_with_maximum_radius(double maximum_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration capsuleCornerConfigurationWithMaximumRadius:static_cast<::CGFloat>(maximum_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_radius(const ViewCornerRadius& radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithRadius:cocoon::internal::native<::NSViewCornerRadius>(radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_top_left_radius(const ViewCornerRadius& top_left_radius, const ViewCornerRadius& top_right_radius, const ViewCornerRadius& bottom_left_radius, const ViewCornerRadius& bottom_right_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithTopLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(top_left_radius) topRightRadius:cocoon::internal::native<::NSViewCornerRadius>(top_right_radius) bottomLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_left_radius) bottomRightRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_right_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_bottom_radius(const ViewCornerRadius& bottom_radius, const ViewCornerRadius& top_left_radius, const ViewCornerRadius& top_right_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformBottomRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_radius) topLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(top_left_radius) topRightRadius:cocoon::internal::native<::NSViewCornerRadius>(top_right_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_left_radius(const ViewCornerRadius& left_radius, const ViewCornerRadius& right_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(left_radius) rightRadius:cocoon::internal::native<::NSViewCornerRadius>(right_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_left_radius(const ViewCornerRadius& left_radius, const ViewCornerRadius& top_right_radius, const ViewCornerRadius& bottom_right_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(left_radius) topRightRadius:cocoon::internal::native<::NSViewCornerRadius>(top_right_radius) bottomRightRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_right_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_radius(const ViewCornerRadius& radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformRadius:cocoon::internal::native<::NSViewCornerRadius>(radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_radius(const ViewCornerRadius& radius, const ViewCornerRadius& top_left_radius, const ViewCornerRadius& top_right_radius, const ViewCornerRadius& bottom_left_radius, const ViewCornerRadius& bottom_right_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformRadius:cocoon::internal::native<::NSViewCornerRadius>(radius) topLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(top_left_radius) topRightRadius:cocoon::internal::native<::NSViewCornerRadius>(top_right_radius) bottomLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_left_radius) bottomRightRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_right_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_right_radius(const ViewCornerRadius& right_radius, const ViewCornerRadius& top_left_radius, const ViewCornerRadius& bottom_left_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformRightRadius:cocoon::internal::native<::NSViewCornerRadius>(right_radius) topLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(top_left_radius) bottomLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_left_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_top_radius(const ViewCornerRadius& top_radius, const ViewCornerRadius& bottom_left_radius, const ViewCornerRadius& bottom_right_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformTopRadius:cocoon::internal::native<::NSViewCornerRadius>(top_radius) bottomLeftRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_left_radius) bottomRightRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_right_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::configuration_with_uniform_top_radius(const ViewCornerRadius& top_radius, const ViewCornerRadius& bottom_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration configurationWithUniformTopRadius:cocoon::internal::native<::NSViewCornerRadius>(top_radius) bottomRadius:cocoon::internal::native<::NSViewCornerRadius>(bottom_radius)]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerConfiguration ViewCornerConfiguration::capsule_corner_configuration() - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerConfiguration capsuleCornerConfiguration]); - } - return ViewCornerConfiguration(nullptr); - } - -#endif -} - -#endif diff --git a/src/generated/view_corner_radii.mm b/src/generated/view_corner_radii.mm deleted file mode 100644 index 39c8eb2b..00000000 --- a/src/generated/view_corner_radii.mm +++ /dev/null @@ -1,68 +0,0 @@ -#include "generated/view_corner_radii.h" -#include "internal.h" - -#ifdef COCOON_MACOS_27 -namespace cocoon -{ - ViewCornerRadii::ViewCornerRadii() : Object(nullptr) - { - } - - ViewCornerRadii::ViewCornerRadii(std::nullptr_t) : Object(nullptr) - { - } - - ViewCornerRadii::ViewCornerRadii(Adopt adopt) : Object(adopt) - { - } - -#ifdef COCOON_MACOS_27 - double ViewCornerRadii::bottom_left() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSViewCornerRadii>(this) bottomLeft]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - double ViewCornerRadii::bottom_right() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSViewCornerRadii>(this) bottomRight]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - double ViewCornerRadii::top_left() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSViewCornerRadii>(this) topLeft]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - double ViewCornerRadii::top_right() const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSViewCornerRadii>(this) topRight]); - } - return {}; - } - -#endif -} - -#endif diff --git a/src/generated/view_corner_radius.mm b/src/generated/view_corner_radius.mm deleted file mode 100644 index af2a87dd..00000000 --- a/src/generated/view_corner_radius.mm +++ /dev/null @@ -1,56 +0,0 @@ -#include "generated/view_corner_radius.h" -#include "internal.h" - -#ifdef COCOON_MACOS_27 -namespace cocoon -{ - ViewCornerRadius::ViewCornerRadius() : Object(nullptr) - { - } - - ViewCornerRadius::ViewCornerRadius(std::nullptr_t) : Object(nullptr) - { - } - - ViewCornerRadius::ViewCornerRadius(Adopt adopt) : Object(adopt) - { - } - -#ifdef COCOON_MACOS_27 - ViewCornerRadius ViewCornerRadius::container_concentric_radius_with_minimum(double minimum_radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerRadius containerConcentricRadiusWithMinimum:static_cast<::CGFloat>(minimum_radius)]); - } - return ViewCornerRadius(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerRadius ViewCornerRadius::fixed_radius(double radius) - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerRadius fixedRadius:static_cast<::CGFloat>(radius)]); - } - return ViewCornerRadius(nullptr); - } - -#endif - -#ifdef COCOON_MACOS_27 - ViewCornerRadius ViewCornerRadius::container_concentric_radius() - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([::NSViewCornerRadius containerConcentricRadius]); - } - return ViewCornerRadius(nullptr); - } - -#endif -} - -#endif diff --git a/src/generated/writing_tools_coordinator.mm b/src/generated/writing_tools_coordinator.mm index 5ef734b1..c132ec2d 100644 --- a/src/generated/writing_tools_coordinator.mm +++ b/src/generated/writing_tools_coordinator.mm @@ -19,44 +19,6 @@ { } -#ifdef COCOON_MACOS_27 - void WritingToolsCoordinator::cancel_text_animations_with_identifiers(const std::vector& identifiers) const - { - if (@available(macOS 27.0, *)) - { - [cocoon::internal::ns<::NSWritingToolsCoordinator>(this) cancelTextAnimationsWithIdentifiers:cocoon::internal::to_array(identifiers, [](const UUID& e) -> id - { - return cocoon::internal::native<::NSUUID>(e); - })]; - } - } - -#endif - -#ifdef COCOON_MACOS_27 - bool WritingToolsCoordinator::show_grammar_presentation_for_range(const Range& range, const WritingToolsCoordinatorContext& context) const - { - if (@available(macOS 27.0, *)) - { - return static_cast([cocoon::internal::ns<::NSWritingToolsCoordinator>(this) showGrammarPresentationForRange:cocoon::internal::to(range) inContext:cocoon::internal::native<::NSWritingToolsCoordinatorContext>(context)]); - } - return {}; - } - -#endif - -#ifdef COCOON_MACOS_27 - UUID WritingToolsCoordinator::start_text_animation(WritingToolsCoordinatorTextAnimation text_animation, const Range& range, const WritingToolsCoordinatorContext& context, WritingDirection writing_direction) const - { - if (@available(macOS 27.0, *)) - { - return cocoon::internal::wrap([cocoon::internal::ns<::NSWritingToolsCoordinator>(this) startTextAnimation:static_cast<::NSWritingToolsCoordinatorTextAnimation>(text_animation) forRange:cocoon::internal::to(range) inContext:cocoon::internal::native<::NSWritingToolsCoordinatorContext>(context) writingDirection:static_cast<::NSWritingDirection>(writing_direction)]); - } - return UUID(nullptr); - } - -#endif - void WritingToolsCoordinator::stop_writing_tools() const { [cocoon::internal::ns<::NSWritingToolsCoordinator>(this) stopWritingTools];