Merge pull request #321 from Nipodemos/update_docs

[Docs] update main README english and pt-br

Merge pull request #321 from Nipodemos/update_docs
[Docs] update main README english and pt-br
Jonny Borges · GitHub
Commit d69e00762f8228b83d59c5984fbe5eaf48259cc8 d69e0076 2 parents 9c6cbaeb 6e6362f7
Showing 2 changed files with 248 additions and 62 deletions
README.md
README.pt-br.md
--- a/README.md
View file @d69e007
+++ b/README.md
View file @d69e007
@@ -14,6 +14,7 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 - [About Get](#about-get)
+- [Installing](#installing)
 - [The Three pillars](#the-three-pillars)
   - [State management](#state-management)
     - [In-depth explanation](#in-depth-explanation)
@@ -33,10 +34,27 @@
 - GetX is an extra-light and powerful solution for Flutter. It combines high performance state management, intelligent dependency injection, and route management in a quick and practical way.
 - GetX is not for everyone, its focus is (performance) on the minimum consumption of resources ([look the benchmarks](https://github.com/jonataslaw/benchmarks)), (productivity) using an easy and pleasant syntax and (organization) allowing the total decoupling of the View from the business logic.
-- GetX will save hours of development, and will extract the maximum performance that your application can deliver, being easy for beginners, and accurate for experts. Navigate without context, open dialogs, snackbars or bottomsheets from anywhere in your code, Manage states and inject dependencies in an easy and practical way. Get is secure, stable, up-to-date, and offers a huge range of APIs that are not present on default framework.
+- GetX will save hours of development, and will extract the maximum performance that your application can deliver, being easy for beginners, and accurate for experts.
+- Navigate without `context`, open `dialogs`, `snackbars` or `bottomsheets` from anywhere in your code, Manage states and inject dependencies in an easy and practical way.
+- Get is secure, stable, up-to-date, and offers a huge range of APIs that are not present on default framework.
 - GetX is not a bloc. It has a multitude of features that allow you to start programming without worrying about anything, but each of these features are in separate containers, and are only started after use. If you only use State Management, only State Management will be compiled. If you only use routes, nothing from the state management will be compiled. You can compile the benchmark repository, and you will see that using only Get state management, the application compiled with Get has become smaller than all other applications that have only the state management of other packages, because nothing that is not used will be compiled into your code, and each GetX solution was designed to be extra lightweight. The merit here also comes from Flutter's AOT which is incredible, and manages to eliminate unused resources like no other framework does.
-**GetX makes your development productive, but want to make it even more productive? Add the extension [GetX extension to VSCode](https://marketplace.visualstudio.com/items?itemName=get-snippets.get-snippets) to your VSCode**
+**GetX makes your development productive, but want to make it even more productive? Add the extension [GetX extension](https://marketplace.visualstudio.com/items?itemName=get-snippets.get-snippets) to your VSCode**. Not available in other IDEs for now.
+
+# Installing
+
+Add Get to your pubspec.yaml file:
+
+```yaml
+dependencies:
+  get:
+```
+
+Import get in files that it will be used:
+
+```dart
+import 'package:get/get.dart';
+```
 # The Three pillars
@@ -103,7 +121,7 @@ This is a simple project but it already makes clear how powerful Get is. As your
 ### In-depth explanation
-**See an more in-depth explanation of state management [here](./docs/en_US/state_management.md). There you will see more examples and also the differente between the simple stage manager and the reactive state manager**
+**See an more in-depth explanation of state management [here](./docs/en_US/state_management.md). There you will see more examples and also the difference between the simple stage manager and the reactive state manager**
 ## Route management
@@ -237,43 +255,63 @@ If you want to know in depth how to change the theme, you can follow this tutori
 ## Other Advanced APIs
 ```dart
-Get.arguments // give the current args from currentScreen
+// give the current args from currentScreen
+Get.arguments
-Get.previousArguments // give arguments of previous route
+// give arguments of previous route
+Get.previousArguments
-Get.previousRoute // give name of previous route
+// give name of previous route
+Get.previousRoute
-Get.rawRoute // give the raw route to access for example, rawRoute.isFirst()
+// give the raw route to access for example, rawRoute.isFirst()
+Get.rawRoute
-Get.routing // give access to Rounting API from GetObserver
+// give access to Rounting API from GetObserver
+Get.routing
-Get.isSnackbarOpen // check if snackbar is open
+// check if snackbar is open
+Get.isSnackbarOpen
-Get.isDialogOpen // check if dialog is open
+// check if dialog is open
+Get.isDialogOpen
-Get.isBottomSheetOpen // check if bottomsheet is open
+// check if bottomsheet is open
+Get.isBottomSheetOpen
-Get.removeRoute() // remove one route.
+// remove one route.
+Get.removeRoute()
-Get.until() // back repeatedly until the predicate returns true.
+// back repeatedly until the predicate returns true.
+Get.until()
-Get.offUntil() // go to next route and remove all the previous routes until the predicate returns true.
+// go to next route and remove all the previous routes until the predicate returns true.
+Get.offUntil()
-Get.offNamedUntil() // go to next named route and remove all the previous routes until the predicate returns true.
+// go to next named route and remove all the previous routes until the predicate returns true.
+Get.offNamedUntil()
-GetPlatform.isAndroid/isIOS/isWeb... //(This method is completely compatible with FlutterWeb, unlike the framework. "Platform.isAndroid")
+//Check in what platform the app is running
+GetPlatform.isAndroid
+GetPlatform.isIOS
+GetPlatform.isWeb
-Get.height / Get.width // Equivalent to the method: MediaQuery.of(context).size.height, but they are immutable. If you need a changeable height/width (like browser windows that can be scaled) you will need to use context.height and context.width
+// Equivalent to the method: MediaQuery.of(context).size.height, but they are immutable.
+// If you need a changeable height/width (like browser windows that can be scaled) you will need to use context.
+Get.height
+Get.width
-Get.context // Gives the context of the screen in the foreground anywhere in your code.
+// Gives the context of the screen in the foreground anywhere in your code.
+Get.context
-Get.contextOverlay // Gives the context of the snackbar/dialog/bottomsheet in the foreground anywhere in your code.
+// Gives the context of the snackbar/dialog/bottomsheet in the foreground anywhere in your code.
+Get.contextOverlay
 ```
 ### Optional Global Settings and Manual configurations
-GetMaterialApp configures everything for you, but if you want to configure Get Manually using advanced APIs.
+GetMaterialApp configures everything for you, but if you want to configure Get manually.
 ```dart
 MaterialApp(
@@ -287,7 +325,9 @@ You will also be able to use your own Middleware within GetObserver, this will n
 ```dart
 MaterialApp(
   navigatorKey: Get.key,
-  navigatorObservers: [GetObserver(MiddleWare.observer)], // Here
+  navigatorObservers: [
+    GetObserver(MiddleWare.observer) // Here
+  ],
 );
 ```
@@ -313,17 +353,15 @@ Get.config(
 # Breaking changes from 2.0
 1- Rx types:
-Before: StringX now: RxString
-Before: IntX now: RxInt
-
-Before: MapX now: RxMax
-
-Before: ListX now: RxList
-
-Before: NumX now: RxNum
-
-Before: RxDouble now: RxDouble
+| Before   | After      |
+| -------- | ---------- |
+| StringX  | `RxString` |
+| IntX     | `RxInt`    |
+| MapX     | `RxMax`    |
+| ListX    | `RxList`   |
+| NumX     | `RxNum`    |
+| RxDouble | `RxDouble` |
 RxController and GetBuilder now have merged, you no longer need to memorize which controller you want to use, just use GetxController, it will work for simple state management and for reactive as well.
@@ -365,8 +403,6 @@ GetMaterialApp(
 )
 ```
-This library will always be updated and implementing new features. Feel free to offer PRs and contribute to them.
-
 # Why I made this package
 The problem that this package tries to solve is to have most of what you need in only one package. One day, when i update some of my apps to work with Flutter 1.9, something bad happened: Everything broke.
@@ -381,4 +417,6 @@ I know this looks a lot like the package being based on my personal experiences,
 Every time I go through a frustrating experience, I write it down in my schedule, and try to resolve it after completing the project.
-And then I decided to make a package that have the three things that you will always use: State management, route management, Dependency injection/management, internationalization, and storage (the last two are still being made)
+And then I decided to make a package that have the three things that you will always use: State management, route management, Dependency injection/management. Eventually i made internationalization, and storage (the last two are still being made)
+
+This library will always be updated and implementing new features. Feel free to offer PRs and contribute to them.
--- a/README.pt-br.md
View file @d69e007
+++ b/README.pt-br.md
View file @d69e007
 ![](get.png)
-*Idiomas: [Inglês](README.md), Português Brasileiro (este arquivo), [Spanish](README-es.md).*
+*Idiomas: [Inglês](README.md), Português Brasileiro (este arquivo), [Espanhol](README-es.md).*
 [![pub package](https://img.shields.io/pub/v/get.svg?label=get&color=blue)](https://pub.dev/packages/get)
 ![building](https://github.com/jonataslaw/get/workflows/build/badge.svg)
@@ -12,7 +12,7 @@
 <a href="https://www.buymeacoffee.com/jonataslaw" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Me compre um café" style="height: 41px !important;width: 174px !important; box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" > </a>
 - [Sobre Get](#sobre-get)
-  - [Instalando e iniciando](#instalando-e-iniciando)
+- [Instalando e iniciando](#instalando-e-iniciando)
 - [Os três pilares](#os-três-pilares)
   - [Gerenciamento de estado](#gerenciamento-de-estado)
     - [Explicação completa](#explicação-completa)
@@ -21,12 +21,20 @@
   - [Gerenciamento de Dependência](#gerenciamento-de-dependência)
     - [Explicação completa](#explicação-completa-2)
 - [Utilidades](#utilidades)
-  - [Outras APIs avançadas e Configurações Manuais](#outras-apis-avançadas-e-configurações-manuais)
+  - [Mudar tema (changeTheme)](#mudar-tema-changetheme)
+  - [Outras APIs avançadas](#outras-apis-avançadas)
+    - [Configurações Globais opcionais e configurações manuais](#configurações-globais-opcionais-e-configurações-manuais)
+- [Breaking Changes da versão 2 para 3](#breaking-changes-da-versão-2-para-3)
+  - [Tipagem Rx](#tipagem-rx)
+  - [RxController e GetBuilder se uniram](#rxcontroller-e-getbuilder-se-uniram)
+  - [Rotas nomeadas](#rotas-nomeadas)
+    - [Porque essa mudança](#porque-essa-mudança)
+- [Porque eu fiz esse package](#porque-eu-fiz-esse-package)
 # Sobre Get
 - Get é uma biblioteca poderosa e extra-leve para Flutter. Ela combina um gerenciador de estado de alta performance, injeção de dependência inteligente e gerenciamento de rotas de uma forma rápida e prática.
-- Get não é para todos, seu foco é
+- Get não é para todos, seu foco é:
   - **Performance**: Já que gasta o mínimo de recursos
   - **Produtividade**: Usando uma sintaxe fácil e agradável
   - **Organização**: Que permite o total desacoplamento da View e da lógica de negócio.
@@ -35,7 +43,7 @@
 - Get é seguro, estável, atualizado e oferece uma enorme gama de APIs que não estão presentes no framework padrão.
 - GetX não é um `bloc` da vida. Ele tem uma variedade de recursos que te permite começar a programar sem se preocupar com nada, mas cada um desses recursos estão em um container separado, ou seja, nenhuma depende da outra para funcionar. Elas só são inicializadas após o uso. Se você usa apenas o gerenciador de estado, apenas ele será compilado. Teste você mesmo, vá no repositório de benchmark do getX e perceberá: usando somente o gerenciador de estado do Get, a aplicação ficou mais leve do que outros projetos que também estão usando só o gerenciador de estado, porque nada que não seja usado será compilado no seu código, e cada recuro do GetX foi feito para ser muito leve. O mérito vem também do AOT do próprio Flutter que é incrível, e consegue eliminar recursos não utilizados de uma forma que nenhum outro framework consegue.
-**GetX faz seu desenvolvimento mais produtivo, mas quer deixá-lo mais produtivo ainda? Adicione a extensão [GetX extension to VSCode](https://marketplace.visualstudio.com/items?itemName=get-snippets.get-snippets) no seu VSCode**. Não disponível para outras IDEs por enquanto.
+**GetX faz seu desenvolvimento mais produtivo, mas quer deixá-lo mais produtivo ainda? Adicione a extensão [GetX extension](https://marketplace.visualstudio.com/items?itemName=get-snippets.get-snippets) no seu VSCode**. Não disponível para outras IDEs por enquanto.
 Quer contribuir no projeto? Nós ficaremos orgulhosos de ressaltar você como um dos colaboradores. Aqui vai algumas formas em que você pode contribuir e fazer Get (e Flutter) ainda melhores
@@ -47,11 +55,7 @@ Quer contribuir no projeto? Nós ficaremos orgulhosos de ressaltar você como um
 Qualquer contribuição é bem-vinda!
-## Instalando e iniciando
-
-<!-- - Flutter Master/Dev/Beta: version 2.0.x-dev 
-- Flutter Stable branch: version 2.0.x
-(procure pela versão mais recente em pub.dev) -->
+# Instalando e iniciando
 Adicione Get ao seu arquivo pubspec.yaml
@@ -60,14 +64,10 @@ dependencies:
   get:
 ```
-Troque seu `MaterialApp()` por `GetMaterialApp()` e aproveite!
+Importe o get nos arquivos que ele for usado:
 ```dart
 import 'package:get/get.dart';
-
-GetMaterialApp( // Antes: MaterialApp(
-  home: HomePage(),
-)
 ```
 # Os três pilares
@@ -85,10 +85,11 @@ Troque `MaterialApp` para `GetMaterialApp`
 void main() => runApp(GetMaterialApp(home: Home()));
 ```
-- **Obs:** Isso não modifica o `MaterialApp` do Flutter, GetMaterialApp não é uma versão modificada do MaterialApp, é só um Widget pré-configurado, que tem como child o MaterialApp padrão. Você pode configurar isso manualmente, mas definitivamente não é necessário. GetMaterialApp vai criar rotas, injetá-las, injetar traduções, injetar tudo que você precisa para navegação por rotas (gerenciamento de rotas). Se você quer somente usar o gerenciado de estado ou somente o gerenciador de dependências, não é necessário usar o GetMaterialApp. Ele somente é necessário para:
+- **Obs:** Isso não modifica o `MaterialApp` do Flutter, GetMaterialApp não é uma versão modificada do MaterialApp, é só um Widget pré-configurado, que tem como child o MaterialApp padrão. Você pode configurar isso manualmente, mas definitivamente não é necessário. GetMaterialApp vai criar rotas, injetá-las, injetar traduções, injetar tudo que você precisa para navegação por rotas (gerenciamento de rotas). Se você quer somente usar o gerenciadro de estado ou somente o gerenciador de dependências, não é necessário usar o GetMaterialApp. Ele somente é necessário para:
   - Rotas
   - Snackbars/bottomsheets/dialogs
   - apis relacionadas a rotas e a ausência de `context`
+  - Internacionalização
 - Passo 2:
 Cria a sua classe de regra de negócio e coloque todas as variáveis, métodos e controllers dentro dela.
@@ -140,7 +141,7 @@ Melhore seus prazos, entregue tudo a tempo sem perder performance. Get não é p
 ## Gerenciamento de rotas
-Veja uma explicação mais completa do gerenciamento de estado [aqui](./docs/pt_BR/route_management.md)
+Veja uma explicação mais completa do gerenciamento de rotas [aqui](./docs/pt_BR/route_management.md)
 Para navegar para uma próxima tela:
@@ -172,6 +173,8 @@ Para navegar para a próxima rota, e receber ou atualizar dados assim que retorn
 var dados = await Get.to(Pagamento());
 ```
+Notou que você não precisou usar `context` para fazer nenhuma dessas coisas? Essa é uma das maiores vantagens de usar o gerenciamento de rotas do GetX. Com isso, você pode executar todos esse métodos de dentro da classe Controller, sem preocupações.
+
 ### Explicação completa
 **GetX funciona com rotas nomeadas também! Veja uma explicação mais completa do gerenciamento de rotas [aqui](./docs/pt_BR/route_management.md)**
@@ -224,26 +227,34 @@ Get.lazyPut<Service>(()=> ApiMock());
 # Utilidades
-## Outras APIs avançadas e Configurações Manuais
+## Mudar tema (changeTheme)
+
+Por favor não use widget acima do GetMaterialApp para atualizar o tome. Isso pode causar keys duplicadas. Várias pessoas estão acostumadas com o jeito normal de criar um Widget `ThemeProvider` só pra alterar o thema do app, mas isso definitivamente NÃO é necessário no Get.
-GetMaterialApp configura tudo para você, mas se quiser configurar Get manualmente, você pode usando APIs avançadas.
+Você pode criar seu tema customizado e simplesmente adicionar dentro do `Get.changeTheme` sem nenhum boilerplate para isso:
 ```dart
-MaterialApp(
-  navigatorKey: Get.key,
-  navigatorObservers: [GetObserver()],
-);
+Get.changeTheme(ThemeData.light())
 ```
-Você também será capaz de usar seu próprio Middleware dentro do GetObserver, isso não irá influenciar em nada.
+Se você quer criar algo como um botão que muda o tema com o toque, você pode combinar duas APIs Get pra isso: a API que checa se o tema dark está sendo aplicado, e a API de mudar o tema, e colocar isso no `onPressed:`
 ```dart
-MaterialApp(
-  navigatorKey: Get.key,
-  navigatorObservers: [GetObserver(MiddleWare.observer)], // Aqui
-);
+Get.changeTheme(
+  Get.isDarkMode
+  ? ThemeData.light()
+  : ThemeData.dark()
+)
 ```
+Quando o modo Dark está ativado, ele vai trocar pro modo light, e vice versa.
+
+Se você quiser saber mais como trocar o tema, você pode seguir esse tutorial no Medium que até ensina persistência do tema usando Get (e SharedPreferences):
+
+- [Dynamic Themes in 3 lines using Get](https://medium.com/swlh/flutter-dynamic-themes-in-3-lines-c3b375f292e3) - Tutorial by [Rod Brown](https://github.com/RodBr).
+
+## Outras APIs avançadas
+
 ```dart
 // fornece os arguments da tela atual
 Get.arguments
@@ -306,4 +317,141 @@ Get.contextOverlay
 ```
+### Configurações Globais opcionais e configurações manuais
+
+GetMaterialApp configura tudo para você, mas se quiser configurar Get manualmente, você pode.
+
+```dart
+MaterialApp(
+  navigatorKey: Get.key,
+  navigatorObservers: [GetObserver()],
+);
+```
+
+Você também será capaz de usar seu próprio Middleware dentro do GetObserver, isso não irá influenciar em nada.
+
+```dart
+MaterialApp(
+  navigatorKey: Get.key,
+  navigatorObservers: [
+    GetObserver(MiddleWare.observer) // Aqui
+  ],
+);
+```
+
+Você pode criar Configurações Globais para o Get. Apenas adicione `Get.config` ao seu código antes de usar qualquer rota ou faça diretamente no seu GetMaterialApp
+
+```dart
+GetMaterialApp(
+  enableLog: true,
+  defaultTransition: Transition.fade,
+  opaqueRoute: Get.isOpaqueRouteDefault,
+  popGesture: Get.isPopGestureEnable,
+  transitionDuration: Get.defaultDurationTransition,
+  defaultGlobalState: Get.defaultGlobalState,
+);
+Get.config(
+  enableLog = true,
+  defaultPopGesture = true,
+  defaultTransition = Transitions.cupertino
+)
+```
+
+# Breaking Changes da versão 2 para 3
+
+## Tipagem Rx
+
+| Antes    | Depois     |
+| -------- | ---------- |
+| StringX  | `RxString` |
+| IntX     | `RxInt`    |
+| MapX     | `RxMax`    |
+| ListX    | `RxList`   |
+| NumX     | `RxNum`    |
+| RxDouble | `RxDouble` |
+
+## RxController e GetBuilder se uniram
+
+RxController e GetBuilder agora viraram um só, você não precisa mais memorizar qual controller quer usar, apenas coloque `GetxController`, vai funcionar para os dois gerenciamento de estados
+
+```dart
+//Gerenciador de estado simples
+class Controller extends GetXController {
+  String nome = '';
+
+  void atualizarNome(String novoNome) {
+    nome = novoNome;
+    update()
+  }
+}
+```
+
+```dart
+class Controller extends GetXController {
+  final nome = ''.obs;
+
+  // não precisa de um método direto pra atualizar o nome
+  // só usar o nome.value
+}
+```
+
+## Rotas nomeadas
+
+Antes:
+
+```dart
+GetMaterialApp(
+  namedRoutes: {
+    '/': GetRoute(page: Home()),
+  }
+)
+```
+
+Agora:
+
+```dart
+GetMaterialApp(
+  getPages: [
+    GetPage(name: '/', page:()=> Home()),
+  ]
+)
+```
+
+### Porque essa mudança
+
+Frequentemente, pode ser necessário decidir qual pagina vai ser mostrada ao usuário a partir de um parâmetro, como um token de login. A forma abordada anteriormente não era flexível, já que não permitia isso.
+
+Inserir a página numa função reduziu significativamente o consumo de RAM, já que as rotas não são alocadas na memória desde o app inicia, e também permite fazer esse tipo de abordagem:
+
+```dart
+
+GetStorage box = GetStorage();
+
+GetMaterialApp(
+  getPages: [
+    GetPage(name: '/', page:(){  
+      return box.hasData('token') ? Home() : Login();
+    })
+  ]
+)
+```
+
+# Porque eu fiz esse package
+
+O problema que esse package tenta resolver é possuir a maioria das funções que preciso num package só.
+
+Um dia, quando eu atualizei um dos meus apps no trabalho para o Flutter 1.9, algo ruim aconteceu: Tudo quebrou.
+
+Todas as bibliotecas pararam de funcionar, na atualização foi bloqueado o uso do hifen "-". Alguns atualizaram seus packages, outros não. Outros eu tive que olhar o porque do projeto não compilar. Outros simplesmente se tornaram incompatíveis com a versão atual, como o `image_extended` que eu até ofereci um PR lá pra conseguir corrigir, e tudo isso por causa de um simples update.
+
+Eu perdi 2 dias de trabalho só procurando por erros pra saber de onde eles vieram.
+
+Eu confesso que foi uma das situações mais estressantes que eu já passei na vida. Foi exatamente nesse dia que eu decidi colocar tudo num package.
+
+Eu sei que parece que esse package é feito só pra sanar minha experiência pessoal, mas eu sou um programador, e eu tento resolver problemas sempre da perspectiva do programador. Eu não me importo em nada mais que fazer a minha vida e de outros programadores mais fácil com esse package.
+
+Sempre que eu passo por uma experiência frustrante, eu escrevo no meu caleundário, e tento resolver depois de completar o projeto.
+
+E então eu decidi fazer um package que tenha três coisas que eu sempre uso: Gerenciamento de Estado, de rotas e de dependências. Depois eu fiz também internacionalização, e persistênsia de dados (estilo Hive)
+
 Essa biblioteca sempre será atualizada e terá sempre nova features sendo implementadas. Sinta-se livre para oferecer PRs e contribuir com o package.