QuasarApp/QtAndroidTools
4
0
Fork 0
mirror of https://github.com/QuasarApp/QtAndroidTools.git synced 2025-04-26 04:54:32 +00:00
Code Issues Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
FalsinSoft 2021-03-29 11:31:59 +02:00
parent 19c82f4f08
commit 42488003b9
2 changed files with 35 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
Documentation/index.html
View File

@ -56,6 +56,7 @@
<li><a href="#GoogleDrive">GoogleDrive</a></li>
<li><a href="#Sharing">Sharing</a></li>
<li><a href="#UserMessagingPlatform">UserMessagingPlatform</a></li>
<li><a href="#Audio">Audio</a></li>
<li><a href="#System">System</a></li>
</ul>
</nav>
@ -89,7 +90,8 @@
QTAT_GOOGLE_ACCOUNT \
QTAT_GOOGLE_DRIVE \
QTAT_SHARING \
QTAT_USER_MESSAGING_PLATFORM</pre>
QTAT_USER_MESSAGING_PLATFORM \
QTAT_AUDIO</pre>
</li>
<li>In the <i>main()</i> body insert the call for initialize the library<br />
<pre class="prettyprint">QtAndroidTools::initializeQmlTools();</pre>
@ -543,7 +545,7 @@ QtAndroidGoogleAccount.signedInAccount.familyName
QtAndroidGoogleAccount.signedInAccount.givenName
QtAndroidGoogleAccount.signedInAccount.photo</pre>
<p>The <i>photo</i> field export the binary image of the account. For show in a standard Image control you can use the generic image provider as follow:</p>
<pre>QtAndroidTools.insertImage("AccountPhoto", QtAndroidGoogleAccount.signedInAccount.photo);
<pre class="prettyprint">QtAndroidTools.insertImage("AccountPhoto", QtAndroidGoogleAccount.signedInAccount.photo);
accountPhoto.source = "image://QtAndroidTools/AccountPhoto";</pre>
<p>For know which type of scopes use for signin you have to check the documentation cause it changes based to the Google resource you want to access in.</p>
<img src="images/googleaccount1.png">
@ -553,7 +555,7 @@ accountPhoto.source = "image://QtAndroidTools/AccountPhoto";</pre>
<p>This tool export a basic set of methods for work with Google Drive.</p>
<p><b>PLEASE NOTE:</b> be very careful in using these methods cause you risk deleting some important files from user's Google drive. It's important to <b>TEST VERY WELL</b> your app before release. I take no responsibility for any damage that can be done using these methods.</p>
<p>For know how to use these methods and how to configure the Google drive access you have to read the official documentation <a href="https://developers.google.com/drive/api/v3/about-sdk" target="_blank">here</a>. As first operation you have to authenticate your app by using the corresponding methods:</p>
<pre>QtAndroidGoogleDrive.authenticate(appName, scopeName)</pre>
<pre class="prettyprint">QtAndroidGoogleDrive.authenticate(appName, scopeName)</pre>
<p>The method return a bool value informing the result of the operation. Scope is used to declare the type of access you want to get for Google Drive. The user must authorize the type of access requested before being able to operate. The list of possible scopes is the following, for use of each scope read the documentation <a href="https://developers.google.com/drive/api/v3/about-auth" target="_blank">here</a>:</p>
<ul>
<li>SCOPE_DRIVE</li>
@ -566,7 +568,7 @@ accountPhoto.source = "image://QtAndroidTools/AccountPhoto";</pre>
<li>SCOPE_DRIVE_SCRIPTS</li>
</ul>
<p>Once got the authorization to access the following methods are available:</p>
<pre>QtAndroidGoogleDrive.getFilesList(query)
<pre class="prettyprint">QtAndroidGoogleDrive.getFilesList(query)
QtAndroidGoogleDrive.getRootId()
QtAndroidGoogleDrive.downloadFile(fileId, localFilePath)
QtAndroidGoogleDrive.uploadFile(localFilePath, mimeType, parentFolderId)
@ -575,7 +577,7 @@ QtAndroidGoogleDrive.isFolder(fileId)
QtAndroidGoogleDrive.moveFile(fileId, folderId)
QtAndroidGoogleDrive.deleteFile(fileId)</pre>
<p>The first method return an array of structs listing the drive files as showed in the example:</p>
<pre>var filesList = QtAndroidGoogleDrive.getFilesList();
<pre class="prettyprint">var filesList = QtAndroidGoogleDrive.getFilesList();
var rootId = QtAndroidGoogleDrive.getRootId();
filesListModel.clear();
@ -599,7 +601,7 @@ for(var i = 0; i < filesList.length; i++)
});
}</pre>
<p>The param <i>query</i> is optional. If you don't pass it the method return the list of all files inside the drive. In case you need a more specific search the documentation about how to use the query is <a href="https://developers.google.com/drive/api/v3/search-files" target="_blank">here</a>. All the files and folder have a string id, the method <i>getRootId()</i> return the id of the root folder. Is possible to download a drive file or upload inside drive. The <i>localFilePath</i> is a full path of the file to upload/download including the file name (also for download). The remaining methods allow to manage the drive files. Remember for download a file you must to have granted the WRITE_EXTERNAL_STORAGE permission. Two signals are used to update info regarding the download/upload operations as follow:</p>
<pre>Connections {
<pre class="prettyprint">Connections {
target: QtAndroidGoogleDrive
function onDownloadProgressChanged(state, progress)
{
@ -649,7 +651,7 @@ for(var i = 0; i < filesList.length; i++)
&lt;data android:mimeType=&quot;image/*&quot;/&gt;
&lt;/intent-filter&gt;</pre>
<p>Regarding the file sharing provider the code is the following:</p>
<pre>&lt;provider android:name=&quot;androidx.core.content.FileProvider&quot;
<pre class="prettyprint">&lt;provider android:name=&quot;androidx.core.content.FileProvider&quot;
android:authorities=&quot;${applicationId}.qtandroidtoolsfileprovider&quot;
android:grantUriPermissions=&quot;true&quot;
android:exported=&quot;false&quot;&gt;
@ -657,17 +659,17 @@ for(var i = 0; i < filesList.length; i++)
&lt;/provider&gt;</pre>
<p>You can name the <i>resource</i> as you prefer but don't change the <i>authorities</i> name cause the tool refer to this label (qtandroidtoolsfileprovider) for configure the correct resource.</p>
<p>For share simple data from your app to other apps the following function are available:</p>
<pre>QtAndroidSharing.shareText(text)
<pre class="prettyprint">QtAndroidSharing.shareText(text)
QtAndroidSharing.shareBinaryData(mimeType, dataFilePath)</pre>
<p>A system window will be showed with all the apps able to receive the data type you want to share as follow:</p>
<img src="images/sharing1.png">
<p>Once the user will select the preferred one the data will be transfered automatically.</p>
<p>In case you want to ask for a file shared by other apps the procedure is a bit different. At first you have to use the following function with the param the file mime type you need:</p>
<pre>QtAndroidSharing.requestSharedFile(mimeType)</pre>
<pre class="prettyprint">QtAndroidSharing.requestSharedFile(mimeType)</pre>
<p>Anothe different systme window will show the apps able to share the file type you need:</p>
<img src="images/sharing2.png">
<p>The selection will open the app sharing the file and the user have to choose the file or cancel the operation. Both actions will return the two events as follow:</p>
<pre>Connections {
<pre class="prettyprint">Connections {
target: QtAndroidSharing
function onRequestedSharedFileReadyToSave(mimeType, name, size)
{
@ -677,11 +679,11 @@ QtAndroidSharing.shareBinaryData(mimeType, dataFilePath)</pre>
}
}</pre>
<p>The second event will inform thet the requested file is not available for various reasons (probably the user cancelled the operation). The first event will export three params named <i>name</i>, <i>size</i> and <i>mimeType</i> with info regarding the user selected file. Please note in this phase the file has not been imported yet. The info will help you to "decide" if the selected file can be imported (for example if the selected file is too much big in size). If you decide the file is correct you have to call the function to import and save somewhere in your app space:</p>
<pre>QtAndroidSharing.saveRequestedSharedFile(filePath)</pre>
<pre class="prettyprint">QtAndroidSharing.saveRequestedSharedFile(filePath)</pre>
<p>In case you are not interested to have the file you have to cancel the operation by call:</p>
<pre>QtAndroidSharing.closeRequestedSharedFile()</pre>
<pre class="prettyprint">QtAndroidSharing.closeRequestedSharedFile()</pre>
<p>Now the opposite part, that's mean reply to shared requested from other apps. As explained in the first part of this section the activity receiving the request is always the main one. This mean the only way to know if our app has been lanuched from another app asking for share something is to check on startup phase as follow:</p>
<pre>Component.onCompleted: {
<pre class="prettyprint">Component.onCompleted: {
if(QtAndroidTools.activityAction === QtAndroidTools.ACTION_SEND)
{
if(QtAndroidTools.activityMimeType === "text/plain")
@ -696,18 +698,18 @@ QtAndroidSharing.shareBinaryData(mimeType, dataFilePath)</pre>
}
}</pre>
<p>Currently the supported actions are the following:</p>
<pre>QtAndroidTools.ACTION_NONE
<pre class="prettyprint">QtAndroidTools.ACTION_NONE
QtAndroidTools.ACTION_SEND
QtAndroidTools.ACTION_SEND_MULTIPLE
QtAndroidTools.ACTION_PICK</pre>
<p>For the first two requests (ACTION_SEND and ACTION_SEND_MULTIPLE) you can receive the shared data sent to you by using the following functions:</p>
<pre>QtAndroidSharing.getReceivedSharedText()
<pre class="prettyprint">QtAndroidSharing.getReceivedSharedText()
QtAndroidSharing.getReceivedSharedBinaryData()
QtAndroidSharing.getReceivedMultipleSharedBinaryData()</pre>
<p>For the action requesting to share a file (ACTION_PICK) you have to show a window for allow the user to select the file he want to import into the requesting app. In the demo app we have only one file to share that the choose is only if you want or not the file:</p>
<img src="images/sharing3.png">
<p>After the user made a selection you have to reply by using the following function:</p>
<pre>QtAndroidSharing.shareFile(fileAvailable, mimeType, filePath)</pre>
<pre class="prettyprint">QtAndroidSharing.shareFile(fileAvailable, mimeType, filePath)</pre>
<p>In case the user want the file you have to set the <i>fileAvailable</i> as true and provide the other params. In the opposite case (the user refused) you have to call this function by set the first param as false without provide the other params.</p>
</div>
<div class="section-txt" id="UserMessagingPlatform">
@ -738,17 +740,27 @@ QtAndroidSharing.getReceivedMultipleSharedBinaryData()</pre>
QtAndroidUserMessagingPlatform.requestConsentForm()</pre>
<p>Once request process finish the signal <i>consentFormRequestResult()</i> is emitted with the results. Any event different from CONSENT_FORM_LOAD_SUCCESS means the form is not available for various reasons. Once obtained the form is necessary to check if it must be showed to the user. You can get such information as follow:</p>
<pre>QtAndroidUserMessagingPlatform.consentStatus()</pre>
<pre class="prettyprint">QtAndroidUserMessagingPlatform.consentStatus()</pre>
<p>Possible returned values are:</p>
<pre>QtAndroidUserMessagingPlatform.CONSENT_FORM_STATUS_UNKNOWN
<pre class="prettyprint">QtAndroidUserMessagingPlatform.CONSENT_FORM_STATUS_UNKNOWN
QtAndroidUserMessagingPlatform.CONSENT_FORM_STATUS_REQUIRED
QtAndroidUserMessagingPlatform.CONSENT_FORM_STATUS_NOT_REQUIRED
QtAndroidUserMessagingPlatform.CONSENT_FORM_STATUS_OBTAINED</pre>
<p>If the status is different from CONSENT_FORM_STATUS_REQUIRED you don't need to show the form. On the contrary, in case of form required or if the user want to change his preferences you can show the form using the call:</p>
<pre>QtAndroidUserMessagingPlatform.showConsentForm()</pre>
<pre class="prettyprint">QtAndroidUserMessagingPlatform.showConsentForm()</pre>
<p>The event <i>consentFormClosed()</i> will inform you when the user closed the form and your app is ready to go. After the user accepted the form some data will be saved in the device and the form will not be required anymore. However if you want to reset these data for restart from scratch you can use the call:</p>
<pre>QtAndroidUserMessagingPlatform.resetConsentInformation()</pre>
<pre class="prettyprint">QtAndroidUserMessagingPlatform.resetConsentInformation()</pre>
<p>This will clean all saved data.</p>
</div>
<div class="section-txt" id="Audio">
<h3>Audio</h3>
<p>This tool allow to get the audio focus and be notified when audio is requested by another application (typical when a call comes in).</p>
<p>You can request and abandon the audio focus using the following calls. If you don't get the audio focus you will not be advised if some other apps request the focus. This is important because, for example, if you are generating a sound and a call comes in, your sound will be generated in parallel with the voice of the call itself. Using this feature you must stop the sound when you lose focus and resume when the focus returns to your application.</p>
<pre class="prettyprint">QtAndroidAudio.requestFocus()
QtAndroidAudio.abandonFocus()</pre>
<p>Once the focus has been acquired, the following variable indicates whether the focus is present or lost.</p>
<pre class="prettyprint">QtAndroidAudio.focus</pre>
</div>
<div class="section-txt" id="System">
<h3>System</h3>
<p>Currently this tool export only the system paths.</p>

3
README.md
View File

@ -55,5 +55,8 @@ Allow to use the Android sharing operation
**UserMessagingPlatform**
Allow to manage consent form
**Audio**
Allow to request audio focus
**System**
Export methods for get some system info