objc2-application-services 0.3.2

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
#[cfg(feature = "objc2")]
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-foundation")]
use objc2_foundation::*;

use crate::*;

#[cfg(feature = "objc2")]
extern_protocol!(
    /// An instance implementing methods in the PDEPlugIn protocol
    /// acts as a factory for PDEPanels. The factory is provided with the type
    /// of printer panel needed (page setup or print dialog) as well as
    /// the current printer. It can use this information to determine which
    /// PDEPanels should be created.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/applicationservices/pdeplugin?language=objc)
    #[cfg(feature = "objc2")]
    pub unsafe trait PDEPlugIn: NSObjectProtocol {
        #[cfg(feature = "objc2-foundation")]
        /// Called to instantiate the principal class of the PDE plug-in.
        ///
        ///
        /// Prior to macOS 13, PDE plug-ins were instantiated with -init, and after
        /// that -initWithBundle: was called expecting a BOOL return. In macOS 13
        /// and later, PDE plug-ins that conform to the PDEPlugIn protocol will be
        /// instantiated with -initWithBundle: as the sole initializer method, returning
        /// the usual instancetype. PDE plug-ins that do not conform to PDEPlugIn
        /// will be instantiated in the old two step way.
        ///
        ///
        /// Parameter `theBundle`: The plug-in's bundle.
        ///
        ///
        /// Returns: Return a valid instance if initialization succeeded and nil otherwise.
        #[unsafe(method(initWithBundle:))]
        #[unsafe(method_family = init)]
        unsafe fn initWithBundle(
            this: Allocated<Self>,
            the_bundle: &NSBundle,
        ) -> Option<Retained<Self>>;

        #[cfg(feature = "objc2-foundation")]
        /// Returns an array of instances conforming to the PDEPanel protocol.
        ///
        ///
        /// Parameter `pdeType`: The type of print panels that should be returned. These kinds are
        /// defined in PMPrintingDialogExtensions.h and include:
        /// kGeneralPageSetupDialogTypeIDStr
        /// - Panels that should be shown in the page setup dialog.
        /// kGeneralPrintDialogTypeIDStr
        /// - Panels that should be shown in the print dialog.
        ///
        ///
        /// Parameter `host`: A print system provided instance that implements methods from the protocol
        /// PDEPlugInCallbackProtocol. The PDEPlugIn can use this parameter to
        /// obtain the current printer or print setting in order to filter the
        /// available panels if there are printer specific PDEPanels in the PDEPlugIn.
        ///
        ///
        /// Returns: An array of instances implementing methods from the PDEPanel protocol.
        /// Each instance represents a panel that will be shown in the printer dialog.
        /// The method may return either nil or an empty array if no panels should be used.
        #[unsafe(method(PDEPanelsForType:withHostInfo:))]
        #[unsafe(method_family = none)]
        unsafe fn PDEPanelsForType_withHostInfo(
            &self,
            pde_type: &NSString,
            host: &ProtocolObject<dyn PDEPlugInCallbackProtocol>,
        ) -> Option<Retained<NSArray<ProtocolObject<dyn PDEPanel>>>>;
    }
);

#[cfg(feature = "objc2")]
extern_protocol!(
    /// A print dialog plugin should have an instance implementing methods
    /// from the PDEPanel protocol. Each such instance handles a single
    /// print dialog panel.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/applicationservices/pdepanel?language=objc)
    #[cfg(feature = "objc2")]
    pub unsafe trait PDEPanel: NSObjectProtocol {
        /// The panel should complete any final preperations it needs
        /// before the panel is shown.
        ///
        ///
        /// The panel may want to use this method to lazily prepare
        /// its user interface.
        #[unsafe(method(willShow))]
        #[unsafe(method_family = none)]
        unsafe fn willShow(&self);

        /// Prepare the panel to be removed from the user's sight.
        ///
        ///
        /// This method is invoked by the print system just before the panel is
        /// removed fromthe user's sight. The panel can use this opportunity
        /// for any final interaction with the user, perhaps to check the user's
        /// input. A panel that needs more interaction with the user, perhaps
        /// because some of the input values were invalid, should return NO.
        /// Returning YES indicates that the panel can be hidden, probably to
        /// show another panel or to dismiss the printing dialog.
        ///
        ///
        /// Returns: Return YES if it is okay to hide panel and NO otherwise.
        #[unsafe(method(shouldHide))]
        #[unsafe(method_family = none)]
        unsafe fn shouldHide(&self) -> bool;

        #[cfg(feature = "objc2-foundation")]
        /// Take the values from the panel's user interface and write them to
        /// the appropriate settings.
        ///
        ///
        /// This is the panel's chance to write the values from its user interface
        /// controls to the permanent store. Depending upon the panel type the values may
        /// be stored in the print settings or into the page format. Panels of type
        /// kGeneralPageSetupDialogTypeIDStr will generally store values into the page
        /// format while panels of type kGeneralPrintDialogTypeIDStr will write to
        /// the print settings. The panel should use the provided PDEPlugInCallbackProtocol
        /// to obtain the settings and tickets it needs to write into.
        ///
        /// A panel will usually be asked to write its values when the user dismisses
        /// the dialog, other than via cancel, or when the user has asked that a preset
        /// be saved.
        #[unsafe(method(saveValuesAndReturnError:_))]
        #[unsafe(method_family = none)]
        unsafe fn saveValuesAndReturnError(&self) -> Result<(), Retained<NSError>>;

        #[cfg(feature = "objc2-foundation")]
        /// Set the panel's user interface elements based upon the appropriate settings.
        ///
        ///
        /// The panel should refresh its user interface elements by reading values from
        /// the page format or print settings. The panel should use the provided
        /// PDEPlugInCallbackProtocol to obtain the settings and tickets it needs to read.
        ///
        /// A panel will usually be asked to read its setting just before it is first
        /// shown and when the user selects a new preset.
        #[unsafe(method(restoreValuesAndReturnError:_))]
        #[unsafe(method_family = none)]
        unsafe fn restoreValuesAndReturnError(&self) -> Result<(), Retained<NSError>>;

        #[cfg(feature = "objc2-foundation")]
        /// The panel takes responsability for displaying user interface elements for the
        /// PPD option keys returned from this call.
        ///
        ///
        /// Any PPD option keys not claimed by a PDEPanel are provided with a dynamically built
        /// user interface in the Printer Features panel.
        #[optional]
        #[unsafe(method(supportedPPDOptionKeys))]
        #[unsafe(method_family = none)]
        unsafe fn supportedPPDOptionKeys(&self) -> Option<Retained<NSArray<NSString>>>;

        #[cfg(feature = "objc2-foundation")]
        /// Inform the panel that, external to the panel, the specified PPD
        /// choice has been made.
        ///
        ///
        /// During PPD conflict resolution the choice for a panel controlled PPD option
        /// may need to be changed by another panel. This call informs the panel
        /// that a setting has been changed. The panel should update any internal data it maintains
        /// in regards to this PPD option key.
        ///
        /// The 'option' and 'choice' values are taken from the printer's PPD. For
        /// example the PPD fragment:
        ///
        /// *OpenUI *TraySwitch/Tray Switch:    Boolean
        /// *TraySwitch True/On: "1 dict dup /TraySwitch true put setpagedevice"
        /// *TraySwitch False/Off: "1 dict dup /TraySwitch false put setpagedevice"
        /// *CloseUI: *TraySwitch
        ///
        /// describes the option 'TraySwitch'. It has 2 choices: 'True' and 'False'.
        /// If another panel caused the choice of the option key 'TraySwitch' to be
        /// altered to 'True'then this method will be called with the 'option' parameter
        /// set to
        /// "
        /// TraySwitch" and the 'choice parameter set to @"True".
        #[unsafe(method(PPDOptionKeyValueDidChange:ppdChoice:))]
        #[unsafe(method_family = none)]
        unsafe fn PPDOptionKeyValueDidChange_ppdChoice(&self, option: &NSString, choice: &NSString);

        #[cfg(feature = "objc2-foundation")]
        /// Return the panel's name.
        ///
        ///
        /// This is the localized name of the panel. It will be placed into
        /// the panel menu.
        #[unsafe(method(panelName))]
        #[unsafe(method_family = none)]
        unsafe fn panelName(&self) -> Retained<NSString>;

        #[cfg(feature = "objc2-foundation")]
        /// Return the panel's kind.
        ///
        ///
        /// A panel's kind is used to allow a plugin to override a system panel.
        /// PMPrintingDialogExtensions.h lists the kinds for the print system provided
        /// panels. If a PDF panel is not supposed to override a print system provided
        /// panel then it should return a unique string for its kind.
        #[unsafe(method(panelKind))]
        #[unsafe(method_family = none)]
        unsafe fn panelKind(&self) -> Retained<NSString>;

        #[cfg(feature = "objc2-foundation")]
        /// Return localized, textual descriptions of the panel's settings.
        ///
        ///
        /// Each key in the dictionary must be an NSString providing the name
        /// of the setting. The value for the key must be an NSString describing
        /// the value for the setting. The strings should be localized for the
        /// current user. For example a key in the dictionary for the copies and
        /// pages panel might have the key 'Page Range' and the value 'All'.
        #[unsafe(method(summaryInfo))]
        #[unsafe(method_family = none)]
        unsafe fn summaryInfo(&self) -> Option<Retained<NSDictionary<NSString, NSString>>>;

        /// The panel should show panel specific help if it is available.
        ///
        ///
        /// Returns: Return YES if the default printing help should be shown and NO otherwise.
        ///
        ///
        /// When a given panel is visible and the user clicks on the help
        /// icon in a print dialog or sheet, the current panel's shouldShowHelp
        /// method is invoked. If the panel implements custom help, the
        /// panel should then present that help and return NO. If this method is not
        /// implemented by a panel or the panel's shouldShowHelp method returns YES,
        /// the default printing help will be presented.
        ///
        /// Invoked only in Mac OS X version 10.5 and later.
        #[optional]
        #[unsafe(method(shouldShowHelp))]
        #[unsafe(method_family = none)]
        unsafe fn shouldShowHelp(&self) -> bool;

        /// The panel should indicate whether the user should be allowed to print.
        ///
        ///
        /// Returns: Return YES unless the printing state for the panel does not allow printing.
        ///
        ///
        /// When a user has performed an action in a print dialog or sheet
        /// that will initiate printing, prior to dismissing the dialog, a panel's
        /// shouldPrint method is invoked, allowing a panel to indicate that the
        /// current state of the dialog should not allow printing. Prior to returning
        /// NO, a panel should present information to the user as to why printing is not
        /// allowed.
        ///
        /// Most panels have no need to implement a 'shouldPrint' method. Typically
        /// a panel manages its state so that it is always valid for the user to
        /// click the print button or otherwise initiate a printing action.
        ///
        /// Invoked only in Mac OS X version 10.5 and later.
        #[optional]
        #[unsafe(method(shouldPrint))]
        #[unsafe(method_family = none)]
        unsafe fn shouldPrint(&self) -> bool;

        /// The print dialog or sheet is closing and a panel should perform
        /// any special tasks that are needed before the window is closed.
        ///
        ///
        /// This is the print panel's chance to peform any special tasks before
        /// the print dialog or sheet goes away. The 'userCanceled' parameter
        /// is true if the print window is being being dismissed because the user
        /// canceled the dialog or sheet.
        ///
        /// One reason for implementing a printWindowWillClose is so that a panel
        /// can remove any notification observers it has added.
        ///
        /// Invoked only in Mac OS X version 10.6 and later.
        #[optional]
        #[unsafe(method(printWindowWillClose:))]
        #[unsafe(method_family = none)]
        unsafe fn printWindowWillClose(&self, user_canceled: bool);
    }
);

#[cfg(feature = "objc2")]
extern_protocol!(
    /// A protocol implemented by the print system so
    /// that printing dialog extensions can obtain information
    /// about the current printer and print job.
    ///
    ///
    /// An print system created instance implementing the protocol,
    /// PDEPlugInCallbackProtocol, is passed to PDEPlugin as part of the PDEPlugIn's
    /// PDEPanelsForType:withHostInfo: message. The PDEPlugIn is expected to
    /// hold on to the passed in instance and to use this PDEPlugInCallbackProtocol
    /// to query the print system for relevant information. The PDEPlugin can
    /// pass the instance implementing PDEPlugInCallbackProtocol to PDEPanels
    /// as needed.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/applicationservices/pdeplugincallbackprotocol?language=objc)
    #[cfg(feature = "objc2")]
    pub unsafe trait PDEPlugInCallbackProtocol {
        #[cfg(feature = "PMDefinitions")]
        /// Return a reference to the current print session.
        #[unsafe(method(printSession))]
        #[unsafe(method_family = none)]
        unsafe fn printSession(&self) -> PMPrintSession;

        #[cfg(feature = "PMDefinitions")]
        /// Return a reference to the print settings object that is
        /// being modified by the printer dialog.
        ///
        ///
        /// This method will return nil if the current print dialog is
        /// not operating on a print settings. The page setup dialog is
        /// the most obvious case where this method will return nil.
        #[unsafe(method(printSettings))]
        #[unsafe(method_family = none)]
        unsafe fn printSettings(&self) -> PMPrintSettings;

        #[cfg(feature = "PMDefinitions")]
        /// Return a reference to the page format that is being used
        /// by the printer dialog.
        ///
        ///
        /// The caller should be prepared for this method to return nil
        /// if the current print dialog is operating without a page format
        /// instance. Today both the print and page setup dialogs will return
        /// a reference to a page format object.
        #[unsafe(method(pageFormat))]
        #[unsafe(method_family = none)]
        unsafe fn pageFormat(&self) -> PMPageFormat;

        #[cfg(feature = "PMDefinitions")]
        /// Return a reference to the current printer instance.
        ///
        ///
        /// When the page setup dialog is displayed this method will return
        /// the user's default printer. When the print dialog is displayed this
        /// method will return the printer currently selected in the print dialog.
        #[unsafe(method(PMPrinter))]
        #[unsafe(method_family = none)]
        unsafe fn PMPrinter(&self) -> PMPrinter;

        #[cfg(feature = "objc2-foundation")]
        /// A PDEPlugIn makes this call to let the print system know that
        /// the plugin intends to alter the choice for a PPD option.
        ///
        ///
        /// When a print dialog plugin intends to change the choice for a
        /// PPD option it notifies the print system with this call. If the
        /// desired choice is in conflict with other currently selected PPD options
        /// then the print system will try to do conflict resolution. This may
        /// include presenting the user with a dialog explaining the conflict
        /// and allowing the user to cancel the change.
        ///
        /// The 'option' parameter names a main key from the printer's PPD.
        /// As an example take the following PPD fragment:
        ///
        /// *OpenUI *MediaType/Paper Type: PickOne
        /// *MediaType Plain/Plain: ""
        /// *MediaType Transparency/Transparency: ""
        /// *CloseUI: *MediaType
        ///
        /// If a panel wishes to switch the value of the option key 'MediaType'
        /// to the choice 'Transparency' then it should invoke this callback
        /// passing
        /// "
        /// MediaType" and @"Transparency" as the 'option' and
        /// 'choice' parameters. If that choice is allowed then YES will be
        /// returned otherwise NO.
        ///
        ///
        /// Returns: Returns YES if the plugin should make the change and returns NO if the
        /// user or the print system would like the change not to occur.
        #[unsafe(method(willChangePPDOptionKeyValue:ppdChoice:))]
        #[unsafe(method_family = none)]
        unsafe fn willChangePPDOptionKeyValue_ppdChoice(
            &self,
            option: &NSString,
            choice: &NSString,
        ) -> bool;
    }
);