1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 17/** 18 * 19 * SubscribedAbstractProperty is base class of ObservedPropertyAbstract 20 * and includes these 3 functions that are part of the SDK. 21 * 22 * SubscribedAbstractProperty<T> is the return type of 23 * - AppStorage static functions Link(), Prop(), SetAndLink(), and SetAndProp() 24 * - LocalStorage methods link(), prop(), setAndLink(), and setAndProp() 25 * 26 * 'T' can be boolean, string, number or custom class. 27 * 28 * Main functions 29 * @see get() reads the linked AppStorage/LocalStorage property value, 30 * @see set(newValue) write a new value to the synched AppStorage/LocalStorage property value 31 * @see aboutToBeDeleted() ends the sync relationship with the AppStorage/LocalStorage property 32 * The app must call this function before the SubscribedAbstractProperty<T> object 33 * goes out of scope. 34 * 35 * @since 7 36*/ 37 38abstract class SubscribedAbstractProperty<T> { 39 /** 40 * reads value of the sync'ed AppStorage/LocalStorage property. 41 * 42 * @since 7 43 * 44 */ 45 public abstract get(): T; 46 47 /** 48 * Set new value, must be of type T, and must not be 'undefined' or 'null'. 49 * Updates the value of value of the sync'ed AppStorage/LocalStorage property. 50 * 51 * @param newValue 52 * 53 * @since 7 54 */ 55 public abstract set(newValue: T): void; 56 57 /** 58 * An app needs to call this function before the instance of SubscribedAbstractProperty 59 * goes out of scrope / is subject to garbage collection. Its purpose is to unregister the 60 * variable from the tw0-way/one-way sync relationship that AppStorage/LocalStorage.link()/prop() 61 * and related functions create. 62 * 63 * @since 7 64 */ 65 public abstract aboutToBeDeleted(): void; 66 67 68 /** 69 * @return the property name if set or undefined 70 * 71 * @since 7 72 */ 73 public abstract info(): string; 74 75 /** 76 * @return the number of current subscribers 77 * This info is useful because only a property with no subscribers is allowed 78 * to be deleted / let out of scope 79 * 80 * @since 7 81 */ 82 public abstract numberOfSubscrbers(): number; 83 84 /** 85 * Notify the property value would have changed. 86 * The framework calls this function automatically upon @see set(). 87 * An application should NOT use this function! 88 * 89 * @since 7, depreciated, do NOT use! 90 */ 91 protected abstract notifyHasChanged(newValue: T); 92 93 /** 94 * Notify the property value would have been read. 95 * The framework calls this function automatically upon @see get() 96 * if it needs this information (usually during initial render of a @Component) 97 * An application should NOT use this function! 98 * 99 * @since 7, depreciated, do NOT use! 100 */ 101 protected abstract notifyPropertyRead(); 102 103 104 /** 105 * Create a new SubscribedAbstractProperty<T> and establish a two-way sync with this property. 106 * We found that managing a 'chain' of SubscribedAbstractProperty<T> is hard to manage and in consequence 107 * easily gets broken by one object being GC'ed. Therefore we have depreciated this method. Do not use it! 108 * 109 * @since 7, depreciated. 110 * 111 */ 112 public abstract createTwoWaySync(subscribeMe?: IPropertySubscriber, info?: string): SubscribedAbstractProperty<T>; 113 114 /** 115 * Create a new SubscribedAbstractProperty<T> and establish a one-way sync with this property. 116 * We found that managing a 'chain' of SubscribedAbstractProperty<T> is hard to manage and in consequence 117 * easily gets broken by one object being GC'ed. Therefore we have depreciated this method. Do not use it! 118 * 119 * @since 7, depreciated. 120 * 121 */ 122 public abstract createOneWaySync(subscribeMe?: IPropertySubscriber, info?: string): SubscribedAbstractProperty<T>; 123} 124 125/** 126 * 127 * AbstractProperty can be understood as a handler or an alias 128 * to a property inside LocalStorage / AppStorage singleton 129 * allows to read the value with @see get and to change the 130 * value with @see set. 131 * 132 * Functions 133 * reads the referenced AppStorage/LocalStorage property value with given name @see get() 134 * write a new value to the AppStorage/LocalStorage property value @see set() 135 * returns the referenced AppStorage/LocalStorage property name @see info() 136 * 137 * Use ref or setAndRef to obtain a AbstractProperty. 138 * 139 * @since 12 140 */ 141interface AbstractProperty<T> { 142 /** 143 * reads value of the referenced AppStorage/LocalStorage property. 144 * 145 * @returns { T } value of the referenced AppStorage/LocalStorage property. 146 * @since 12 147 */ 148 get(): T; 149 150 /** 151 * Set new value, must be of type T, can be 'undefined' or 'null'. 152 * Updates the value of the referenced AppStorage/LocalStorage property. 153 * 154 * @param { T } newValue new value set to AppStorage/LocalStorage 155 * @since 12 156 */ 157 set(newValue: T): void; 158 159 /** 160 * returns the name of the referenced property 161 * 162 * @returns { string } name of the referenced property 163 * @since 12 164 */ 165 info(): string; 166} 167