Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Applications.ComponentBased] Enhance API descriptions #6373

Merged
merged 2 commits into from
Sep 30, 2024
Merged

[Applications.ComponentBased] Enhance API descriptions #6373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1013a06
[Applications.ComponentBased] Enhance API descriptions
upple Sep 26, 2024
b4eac56
Add missing since_tizen tag
upple Sep 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions ...zen.Applications.ComponentBased/Tizen.Applications.ComponentBased.Common/BaseComponent.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@
namespace Tizen.Applications.ComponentBased.Common
{
/// <summary>
/// This is a base-component class.
/// It provides common functions of FrameComponent and ServiceComponent.
/// Represents the base class for components, providing common functionalities for both FrameComponent and ServiceComponent.
/// </summary>
/// <remarks>
/// This class cannot be registered by ComponentBased applications.
/// This class cannot be registered directly by ComponentBased applications.
/// It serves as a base class to be inherited by other components.
/// </remarks>
/// <since_tizen> 6 </since_tizen>
public abstract class BaseComponent
Expand Down Expand Up @@ -75,26 +75,26 @@ public abstract class BaseComponent
public event EventHandler<TimeZoneChangedEventArgs> TimeZoneChanged;

/// <summary>
/// A component instance ID.
/// Gets the unique instance ID of the component.
/// It will be created after OnCreate method is invoked.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public string Id { get; private set; }

/// <summary>
/// A component ID
/// Gets the ID of the component.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public string ComponentId { get; private set; }

/// <summary>
/// Parent object
/// Gets the parent application object to which the component belongs.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public ComponentBasedApplication Parent { get; private set; }

/// <summary>
/// Finish current component
/// Finishes the current component.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public void Finish()
Expand Down Expand Up @@ -128,18 +128,18 @@ internal void Bind(IntPtr handle, string compId, string instanceId, ComponentBas
}

/// <summary>
/// Overrides this method if want to handle behavior to restore the previous status.
/// Override this method to handle restoring the previous state of the component.
/// </summary>
/// <param name="c">Contents. It can be used only in the callback. To use outside, make a copy. </param>
/// <param name="c">A bundle containing the saved state of the component. It can only be used within the callback. To use it outside, create a copy.</param>
/// <since_tizen> 6 </since_tizen>
public virtual void OnRestoreContents(Bundle c)
{
}

/// <summary>
/// Overrides this method if want to handle behavior to save current status.
/// Override this method to handle saving the current state of the component.
/// </summary>
/// <param name="c">Contents. It can be used only in the callback. To use outside, make a copy. </param>
/// <param name="c">A bundle containing the current state of the component. It can only be used within the callback. To use it outside, create a copy.</param>
/// <since_tizen> 6 </since_tizen>
public virtual void OnSaveContent(Bundle c)
{
Expand Down Expand Up @@ -181,17 +181,18 @@ internal void OnTimeZoneChangedCallback(string timeZone, string timeZoneId)
}

/// <summary>
/// Sends the launch request asynchronously.
/// Sends a launch request asynchronously.
/// </summary>
/// <remarks>
/// To use group mode, you must use this function instead of SendLaunchRequestAsync().
/// Use this method to send a launch request with group mode enabled.
/// If group mode is not required, you can use SendLaunchRequestAsync() instead.
/// </remarks>
/// <param name="control">appcontrol object</param>
/// <param name="replyAfterLaunching">The callback function to be called when the reply is delivered.</param>
/// <returns>A task with the result of the launch request.</returns>
/// <param name="control">The AppControl object representing the request details.</param>
/// <param name="replyAfterLaunching">The callback function to be invoked when the reply is received.</param>
/// <returns>A task representing the result of the launch request.</returns>
/// <exception cref="ArgumentException">Thrown when failed because of the argument is invalid.</exception>
/// <exception cref="InvalidOperationException">Thrown when fail to set component information to the AppControl.</exception>
/// <exception cref="Exceptions.AppNotFoundException">Thrown when the application to run is not found.</exception>
/// <exception cref="InvalidOperationException">Thrown when there is a failure in setting the component information in the AppControl.</exception>
/// <exception cref="Exceptions.AppNotFoundException">Thrown when the target application is not found.</exception>
/// <exception cref="Exceptions.LaunchRejectedException">Thrown when the launch request is rejected.</exception>
/// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
/// <since_tizen> 6 </since_tizen>
Expand Down
76 changes: 59 additions & 17 deletions ...ions.ComponentBased/Tizen.Applications.ComponentBased.Common/ComponentBasedApplication.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,13 @@
namespace Tizen.Applications.ComponentBased.Common
{
/// <summary>
/// The class for supporting multi-components based application model.
/// Represents the base class for a multi-component based application.
/// This class allows the creation and management of multiple application components, such as Frame, Service, and Widget components.
/// </summary>
/// <remarks>
/// This abstract class provides the core structure for applications that consist of multiple components.
/// Each component has its own lifecycle, and the framework handles these lifecycles independently.
/// </remarks>
/// <since_tizen> 6 </since_tizen>
public abstract class ComponentBasedApplication : Application
{
Expand All @@ -30,12 +35,24 @@ public abstract class ComponentBasedApplication : Application
private Interop.CBApplication.CBAppLifecycleCallbacks _callbacks;

/// <summary>
/// Initializes the ComponentBasedApplicationBase class.
/// Initializes a new instance of the <see cref="ComponentBasedApplication"/> class with the specified component type information.
/// </summary>
/// <param name="typeInfo">The component type information.
/// The key should be a class type of FrameComponent or SubComponent subclass.
/// The value should be a component id which is declared in tizen-manifest.xml.
/// </param>
/// <param name="typeInfo">A dictionary where the key is the component class type (FrameComponent, ServiceComponent or WidgetComponent subclass),
/// and the value is the component ID defined in the tizen-manifest.xml file.</param>
/// <remarks>
/// This constructor sets up the necessary callbacks for the application lifecycle and registers the provided components.
/// </remarks>
/// <example>
/// <code>
/// IDictionary&lt;Type, string&gt; components = new Dictionary&lt;Type, string&gt;()
/// {
/// { typeof(MyFrameComponent), "frameComponentId" },
/// { typeof(MyServiceComponent), "serviceComponentId" }
/// };
/// ComponentBasedApplication app = new MyApplication(components);
/// app.Run(args);
/// </code>
/// </example>
/// <since_tizen> 6 </since_tizen>
public ComponentBasedApplication(IDictionary<Type, string> typeInfo)
{
Expand All @@ -53,11 +70,19 @@ public ComponentBasedApplication(IDictionary<Type, string> typeInfo)
}

/// <summary>
/// Registers a component.
/// Registers a component with the specified type and ID.
/// </summary>
/// <param name="compType">Class type</param>
/// <param name="compId">Component ID</param>
/// <exception cref="ArgumentException">Thrown when component type is already added or not sub-class of FrameComponent or ServiceComponent</exception>
/// <param name="compType">The type of the component to register. Must be a subclass of FrameComponent, ServiceComponent, or WidgetComponent.</param>
/// <param name="compId">The ID of the component, defined in the tizen-manifest.xml file.</param>
/// <exception cref="ArgumentException">Thrown when the component type is already registered or not sub-class of FrameComponent, ServiceComponent or WidgetComponent.</exception>
/// <remarks>
/// This method ensures that only valid component types are registered. The component ID must be unique.
/// </remarks>
/// <example>
/// <code>
/// app.RegisterComponent(typeof(MyFrameComponent), "frameComponentId");
/// </code>
/// </example>
/// <since_tizen> 6 </since_tizen>
public void RegisterComponent(Type compType, string compId)
{
Expand Down Expand Up @@ -98,8 +123,13 @@ public void RegisterComponent(Type compType, string compId)
/// <summary>
/// Runs the application's main loop.
/// </summary>
/// <param name="args">Arguments from commandline.</param>
/// <param name="args">The arguments passed from the command line.</param>
/// <exception cref="InvalidOperationException">Thrown when component type is already added to the component.</exception>
/// <example>
/// <code>
/// app.Run(args);
/// </code>
/// </example>
/// <since_tizen> 6 </since_tizen>
public override void Run(string[] args)
{
Expand All @@ -121,7 +151,7 @@ public override void Run(string[] args)
}

/// <summary>
/// Exits the main loop of the application.
/// Exits the application's main loop.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public override void Exit()
Expand Down Expand Up @@ -166,31 +196,43 @@ private void OnFinishedNative(IntPtr data)
}

/// <summary>
/// This method will be called before running main-loop
/// Called before the main loop starts.
/// </summary>
/// <param name="args"></param>
/// <param name="args">The arguments passed from the command line.</param>
/// <remarks>
/// Override this method to handle any initialization logic before the application enters the main event loop.
/// </remarks>
/// <since_tizen> 6 </since_tizen>
protected virtual void OnInit(string[] args)
{
}

/// <summary>
/// This method will be called after exiting main-loop
/// Called after the main loop exits.
/// </summary>
/// <remarks>
/// Override this method to handle any cleanup logic after the application has finished running.
/// </remarks>
/// <since_tizen> 6 </since_tizen>
protected virtual void OnFinished()
{
}

/// <summary>
/// This method will be called to start main-loop
/// Called to start the main loop of the application.
/// </summary>
/// <remarks>
/// This is an abstract method that must be implemented by derived classes to define the behavior when the application starts.
/// </remarks>
/// <since_tizen> 6 </since_tizen>
protected abstract void OnRun();

/// <summary>
/// This method will be called to exit main-loop
/// Called to exit the main loop of the application.
/// </summary>
/// <remarks>
/// Override this method to handle any logic needed before the application exits.
/// </remarks>
/// <since_tizen> 6 </since_tizen>
protected virtual void OnExit()
{
Expand Down
37 changes: 23 additions & 14 deletions ...en.Applications.ComponentBased/Tizen.Applications.ComponentBased.Common/FrameComponent.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,19 @@
namespace Tizen.Applications.ComponentBased.Common
{
/// <summary>
/// The class for showing UI module
/// Represents a base class for UI components in the component-based application model.
/// This class provides methods for handling the lifecycle and state of UI components.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public abstract class FrameComponent : BaseComponent
{
/// <summary>
/// Gets the display status of a component.
/// Gets the current display status of the component.
/// </summary>
/// <exception cref="InvalidOperationException">Thrown when component type is already added to the component.</exception>
/// <value>
/// The current <see cref="DisplayStatus"/> of the component.
/// </value>
/// <exception cref="InvalidOperationException">Thrown when the display status cannot be retrieved.</exception>
/// <since_tizen> 6 </since_tizen>
public DisplayStatus DisplayStatus
{
Expand All @@ -43,55 +47,60 @@ public DisplayStatus DisplayStatus
}

/// <summary>
/// Overrides this method to handle behavior when the component is launched.
/// Called when the component is launched. Override this method to implement custom launch behavior.
/// </summary>
/// <returns>True if a service component is successfully created</returns>
/// <returns>
/// <c>true</c> if the service component is successfully created; otherwise, <c>false</c>.
/// </returns>
/// <since_tizen> 6 </since_tizen>
public abstract bool OnCreate();

/// <summary>
/// Overrides this method to create window. It will be called before OnCreate method.
/// Called to create the window for the component. Override this method to provide a custom window.
/// This method will be called before <see cref="OnCreate"/> method.
/// </summary>
/// <returns>Window object to use</returns>
/// <returns>
/// An <see cref="IWindowInfo"/> object that represents the created window.
/// </returns>
/// <since_tizen> 6 </since_tizen>
public abstract IWindowInfo CreateWindowInfo();

/// <summary>
/// Overrides this method if want to handle behavior when the component receives the appcontrol message.
/// Called when the component receives an app control message. Override this method to handle app control messages.
/// </summary>
/// <param name="appControl">appcontrol object</param>
/// <param name="restarted">True if it was restarted</param>
/// <param name="appControl">The <see cref="AppControl"/> object containing the app control data.</param>
/// <param name="restarted"><c>true</c> if the component was restarted; otherwise, <c>false</c>.</param>
/// <since_tizen> 6 </since_tizen>
public virtual void OnStart(AppControl appControl, bool restarted)
{
}

/// <summary>
/// Overrides this method if you want to handle the behavior when the component is resumed.
/// Called when the component is resumed. Override this method to handle resume behavior.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public virtual void OnResume()
{
}

/// <summary>
/// Overrides this method if you want to handle the behavior when the component is paused.
/// Called when the component is paused. Override this method to handle pause behavior.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public virtual void OnPause()
{
}

/// <summary>
/// Overrides this method if you want to handle the behavior when the component is stopped.
/// Called when the component is stopped. Override this method to handle stop behavior.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public virtual void OnStop()
{
}

/// <summary>
/// Overrides this method if want to handle behavior when the component is destroyed.
/// Called when the component is destroyed. Override this method to handle destruction behavior.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public virtual void OnDestroy()
Expand Down
19 changes: 12 additions & 7 deletions ....Applications.ComponentBased/Tizen.Applications.ComponentBased.Common/ServiceComponent.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,33 +19,38 @@
namespace Tizen.Applications.ComponentBased.Common
{
/// <summary>
/// The class for showing service module
/// Represents a base class for service components in the component-based application model.
/// This class provides methods for handling the lifecycle and state of service components.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public abstract class ServiceComponent : BaseComponent
{
/// <summary>
/// Overrides this method to handle behavior when the component is created.
/// Called when the service component is created. Override this method to implement custom creation behavior.
/// </summary>
/// <returns>True if a service component is successfully created</returns>
/// <returns>
/// <c>true</c> if the service component is successfully created; otherwise, <c>false</c>.
/// </returns>
/// <since_tizen> 6 </since_tizen>
public abstract bool OnCreate();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a missing since tag.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I added the since tag, the ACR-Required tag was added.
So I kept it as before.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can ignore ACR-Requried. Because, the tag was added when ACR was accepted.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I see. I'll prepare the patch.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.


/// <summary>
/// Overrides this method if want to handle behavior when the component receives the start command message.
/// Called when the service component receives a start command message. Override this method to handle start command behavior.
/// </summary>
/// <param name="appControl">appcontrol object</param>
/// <param name="restarted">True if it was restarted</param>
/// <param name="appControl">The <see cref="AppControl"/> object containing the app control data.</param>
/// <param name="restarted"><c>true</c> if the component was restarted; otherwise, <c>false</c>.</param>
/// <since_tizen> 6 </since_tizen>
public virtual void OnStartCommand(AppControl appControl, bool restarted)
{
}

/// <summary>
/// Overrides this method if want to handle behavior when the component is destroyed.
/// Called when the service component is destroyed. Override this method to handle destruction behavior.
/// </summary>
/// <since_tizen> 6 </since_tizen>
public virtual void OnDestroy()
{
}
}
}

Loading
Loading